Information for Maintainers

Related topics: BitKeeperNotes, DocumentationNotes, SoftwareDevelopment, ssh notes, TravisCINotes

Feel free to make improvements this topic.

When you become a project committer

• What to expect as a project committer

How do I use bk?

See BitKeeperNotes for information on how to use bk.

How project committers can obtain bk

Project committers can obtain bk by following the instructions at getting bk .

About the -stable and -dev repositories

NTP uses a two-repository model. The -stable repository is the most-recently released production code. In general, only "significant" bugfixes are applied to -stable.

If there is a bug that affects both -stable and -dev, due to the way that bk works best it is much easier to fix the bug in a -stable repo and pull those changes into -dev.

While it is possible to fix the bug in -dev first and then backport the change into -stable this is generally much more difficult.

-dev is always a superset of -stable. Put another way, it must always be possible to pull changes from -stable to -dev. This means if a patch will be included in -stable that the patch must cleanly pull into -dev. The next section describes how to work on a bug to be sure this remains the case.

-stable must always be able to pull cleanly into -dev.

-stable and its documentation

Dave Mills only supports -dev. If any patches are made to -stable we should also update the documentation in html/ when appropriate. If the patch will also be used for -dev things become more interesting as Harlan needs to take extra steps to synchronize documentation changes with Dave.

Code Review

See Code Review for more information.

How to work on a bug using BitKeeper

-stable must always pull cleanly into -dev.

Also see the Code Review page.

If you want to fix something in both ntp-stable and ntp-dev it will be much easier if you:

• Fix the bug in ntp-stable and commit your changes
• bk pull that fix to an ntp-dev repo
• recheck your fix, and make and commit any additional changes in ntp-dev

Fixing a bug in both -stable and -dev

Also see the Code Review page.

Here are the steps I recommend you take when working on, say, bug 246 in both ntp-stable and ntp-dev:

• ACCEPT the bug.
• Go to the Flags section (upper right-hand side of the bug):
  • For -stable bugs, you must request that the bug block the -stable release.
  • ? is the value you want.
  • -stable patches must be flagged to block the release or they will likely be missed.
  • You may request that the bug block the -dev release. ? is the value you want.
  • See BugzillaBlockingReleaseFlag for more information.
• in your home directory on psp-xxx:
• bk clone bk://bk.ntp.org/ntp-stable ntp-stable-246
• bk clone bk://bk.ntp.org/ntp-dev ntp-dev-246
• cd ntp-stable-246
• ./bootstrap
• repeat as needed:
  • edit away
  • bk ci ... and bk commit, or bk citool as often as you wish
    • Use a checkin comment of the form: [BUG 246] ...
  • if you want to revert a change you've made which is in one of the last ChangeSets in your repo, and you have not yet pulled that change into your corresponding -dev repo, and have not pushed or pulled or cloned that ChangeSet to any repo you need to continue to maintain, bk collapse can be very convenient. Use bk collapse -e -aRev where Rev is the ChangeSet immediately prior to the one containing the (first) change to be reverted/collapsed. This results in all the files modified after Rev still having the most current changes, but no longer having been checked in or committed to ChangeSets, as the repo history has been rolled back to Rev. Revert as little or as much of your changes as needed, then bk citool will allow you to quickly repeat all the checkin/commit operations, including preserving the comments from before the bk collapse. When there were multiple revisions to a single file collapsed, the saved comments for each collapsed revision are separated by a line of three dashes.
  • bk pull to stay up-to-date, as needed/desired
  • if a Makefile.am or configure.{ac,in} is changed, run the build script on psp-xxx. For that matter, if any ChangeSet was pulled run the build script on psp-xxx to make sure the version file is properly updated.
• As needed:
  • cd ntp-dev-246
  • bk pull ../ntp-stable-246
  • If needed, run ./bootstrap
  • build and test
• When you think you are finished, make sure ntp-stable-246 is ready to go:
  • Add a suitable comment to the ntp-stable-246/ChangeLog file (and check in this change). See ChangeLogMaintenance for more information.
  • bk status -v to make sure no changes are pending. If there are, run bk commit or bk citool.
    • Use a checkin comment of the form: [BUG 246] ... (note this is the also the form used for the ChangeLog file).
  • If you have made many commits to produce your work, please consider looking at bk help collapse and running it if you think it will be worthwhile. If you want to be especially careful, clone your work into a new directory and run bk collapse in the new directory.
  • bk pull to get any changes that may have been applied to ntp-stable.
  • run flock-build and make sure everything builds in ntp-stable-246.
  • Check A.*/make.log
• Make sure ntp-dev-246 is ready to go:
  • Note that there will be no need to make an entry in ntp-dev-246/ChangeLog because that entry will be incorporated automatically from ntp-stable-246/ChangeLog.
  • Make sure your changes to ntp-stable-246 have been pulled to ntp-dev-246.
  • bk pull to get any chages that may have been applied to ntp-dev.
  • run flock-build and make sure everything builds in ntp-dev-246.
  • Check A.*/make.log
• In bugzilla:
  • Mark the bug as RESOLVED/READY.
  • with a bugzilla comment of: Please pick up the changes in psp-xxx:ntp-stable-246 and psp-xxx:ntp-dev-246.
  • Make sure the appropriate BugzillaBlockingReleaseFlag has been requested.

Note that you can also do the work somewhere besides psp-xxx. When you are ready, please get your working repository to your home directory on psp-xxx so you can run flock-build in order to make sure the code compiles properly on a number of different platforms. You can use bk clone, bk push, or bk pull to copy your changes, or some other method of your choosing.

Fixing a bug in -dev only

This is pretty much the same as the previous case, except you only need to deal with ntp-dev-246.

Also see the Code Review page.

Backporting a fix from -dev to -stable

You remember this is more difficult, right?

Create your ntp-{dev,stable}-246 repositories as described above.

Get the changes you have ported into -dev into ntp-stable-246.

Do the needed work.

Pull ntp-stable-246 into ntp-dev-246 and make sure nothing has broken.

Run bk pull -i and then run bk resolve to manually finish the merge.

Note that the ChangeLog entry will need to be moved from the -dev section to the -stable section. See ChangeLogMaintenance for more information.

As for the other files, I currently recommend that you run bk resolve and for each file where you do not want to import any changes, use !cp $BK_LOCAL $BK_MERGE followed by C for each file. This will install the "local" file (from -dev) as the merged file.

Make sure the result is OK, and then commit your changes.

With this approach we can still pull changes from -stable to -dev.

The worse choice is to manually resolve the changes telling bk to "use the local file" instead of the "remote file". This keeps the -dev version of the file, but breaks the association between the -stable and -dev versions of the file.

You might be able to use bk treediff ntp-dev-246 ntp-dev to be sure the process has not broken anything.

When you are done you may choose to run bk collapse to put the collection of changes into a single ChangeSet.

Also see the Code Review page.

(Please add more information here, as appropriate.)

Checking for flock-build errors

Once a flock-build has completed, please spot-check the end of each make.log file to ensure it completed successfully. For example:

user@psp-xxx>cd ~/ntp-dev-repo
user@psp-xxx>less A.*/make.log

There will be a couple of dozen make.log files. Press the '>' key in less to jump to the end of each file, then when you are ready to look at the next one, press space to switch to the next file and '>' again.

DaveHart has a script ~hart/bin/flock-scan which checks for error:, errors., and the grep regexp \*\*\*.* Error, which is to say * followed by anything followed by Error. Just in case those miss something, it also tails the logs with a short delay between each.

Alternatively, at bare minimum check for error: in the make.log files:

user@psp-xxx>fgrep error: A.*/make.log

Notification of topic changes

Add your WikiName to WebNotify to receive notification of topic changes in the Dev Web. There are WebNotify in each of the Webs which make up this TWiki.

This is a subscription service to be automatically notified by e-mail when topics change in this TWiki web. This is a convenient service, so you do not have to come back and check all the time if something has changed.

The notification interval is 2 hours. If you wish to have more control over notification of changes (e.g. immediate notification of changes to Webs or topics, notifications defined with regexes) you should take a look at the NotificationPlugin. To use the NotificationPlugin you must create a Users.YourWikiNameNotifyList and populate it with the contents of the NotificationPluginListTemplate.

SSH tip for easier flock builds

First, know that pogo is fast becoming less useful to us, and the flock at UDel is shrinking.

The psp-* machines are slowly growing however, and we also a growing collection of machines in our buildbot farm. More on this soon.

Consider creating a passwordless ssh key on pogo and add the public key to your ~/.ssh/authorized_keys file. This will allow flock-build to run easily.

A good ~/.ssh/config file is:

Host *
  ForwardX11 yes
  #ForwardX11Trusted yes
  PreferredAuthentications gssapi-with-mic,hostbased,publickey,pubkey,password,keyboard-interactive
  IdentityFile ~/.ssh/id_dsa
  IdentityFile ~/.ssh/id_rsa

Accessing repositories from bk on Windows

DaveHart has done this using putty and its command-line ssh clone plink. Set BK_RSH=plink and add c:\program files\putty to your PATH in the system control panel applet ("advanced system settings" under Vista). Start Pageant and load your SSH key used for psp-xxx. Tweak putty settings to your liking and save settings under the name "psp-xxx". Then verify from a shell that plink is working:

C:\>plink -v -ssh YOU@psp-xxx date
...
Started a shell/command
Wed Feb 11 22:57:08 UTC 2009
Server sent command exit status 0
Disconnected: All channels closed

Who needs NTP when you can script ssh and date? ;) If that works you should be able to do something like:

C:\ntp>bk clone YOU@psp-xxx:ntp-dev-1234

and pull down psp-xxx:~YOU/ntp-dev-1234 into c:\ntp\ntp-dev-1234. Then you can edit away, check in files with comments, collect them into ChangeSets, and bk push to update the parent psp-xxx repo in your homedir with your offline changes. You need to do a two-step pull process to keep your Windows repo current as ntp-dev progresses. First bk pull on psp-xxx, then on your Windows child repo. You only use bk push on your Windows repo, updating your psp-xxx repo. On psp-xxx, Harlan will bk pull from your repo into ntp-dev.

NOTE: If you're using Windows Vista or Windows 7 without disabling User Account Controls, plink will fail after prompting for a password (instead of using pageant) if it is run from a shell started with "Run As Administrator" (an elevated shell). So to bk clone, bk pull, or bk push, make sure (Administrator) doesn't appear in your shell's window title. On the other hand, to build (mkver.bat's regedit use in particular) you do want to be using an elevated shell...

Confusing, you say? I haven't even begun to confuse you. The reason it fails is Vista is virtualizing non-elevated access to some files by cloning the administrator-accessible versions into a tree under the user's home directory. Pageant and plink apparently are communicating using files in a directory Vista UAC so chooses to virtualize. plink correctly detects pageant is running and tries to communicate when invoked elevated, but since it's getting the original unvirtualized directory contents while pageant is most likely running not elevated, it's trying to communicate using the per-user sandboxed virtualized directory contents. It's split-reality virtualization. There are scary implications for ntp.conf and ntp.log stored in \Program Files\ntp\etc which is so virtualized.

Use bk clone liberally to back up your committed work in progress, such as before a pull of upstream changes. It sometimes reports an error and leaves the repo in a state that is not obvious how to repair. There are inconsistent line endings in some cases (Unix LF only, rather than Windows CR LF) such as bk export -tpatch. On screen, no problem, but redirect the output to a file and open with a non-programmers editor and you're likely to see one big line. The same issue affects bk pull and bk push when resolving a merge conflict, or bk resolve. When you use the e command to edit the automerged file, the file is generated with mixed Unix and Windows line endings. As long as your editor doesn't mind or can convert, no problem. If your favorite editor doesn't get along with bare LF line endings, wrap its invocation with a batch file that uses http://davehart.net/anynl to normalize the line endings. Visual Studio 2008, for example, will work fine with a file with mixed line endings (only the changed lines have bare LFs during resolve, most of the lines have CR LF) but it triggers a prompt that can be avoided by pointing EDITOR at a normalizing batch file using anynl or similar.

To export a patch and convert the line endings to Windows: bk export -tpatch -rRev1,Rev2 | anynl >patch.txt

After some refinement over time, my paranoid batch file is:

@rem grab base filename without directories
@for %%I in (%1) do @set vsedit=vsedit_t_%%~nxI
@rem first anynl is used in place of copy because it won't puke on "dir/file.ext" with forward slash
@anynl <"%1" >"%vsedit%"
@anynl <"%vsedit%" >"%1"
@del "%vsedit%"
@start /wait "" "C:\Program Files\Microsoft Visual Studio 9.0\Common7\IDE\VCExpress.exe" %1
@anynl <"%1" >"%vsedit%"
@anynl -unix <"%vsedit%" >"%1"
@del "%vsedit%"
@set vsedit=

Correct the path to your editor, then save as vsedit.bat on your path and set EDITOR=vsedit (in computer properties or your development environment setup batch file).

This version also works around another subtlety, bk resolve is passing forward slashes in the path to the file to be edited. While it's true at the API level / and \ are equivalent path separators, depending on other programs (such as cmd.exe's copy builtin) getting this right is iffy. In the case of copy, DOS compatibility trumped Unix compatbiliity apparently. DOS also had the same situation from the first version that had a path separator, 2.0. The API considers them equivalent but only a minority of programs treated them as such. There was once a SWITCHCHAR environment variable to be like Unix, setting SWITCHCHAR to hyphen freed up / to be used as a path separator unambiguously in the shell. As an obscure non-default setting it invited more trouble than it was worth because few programs handled it and was dropped.

Getting back to the batch file, it normalizes line endings twice, first to Windows style before invoking the editor, then to Unix style before returning to bk resolve. You may want to remove the conversion "back" to Unix line endings if programs other than bk use your EDITOR environment variable. I did it that way out of an abundance of caution, not wanting to trip over any more BK for Windows quirks than necessary to get my NTP work done. My hunch is bk resolve like anynl is fine with any mixture of Unix and Windows line endings, and so it is safe to remove the two post-editor anynl invocations and the following del.