The Problem
Vesta's core repository tools do not include any method to keep track of the status of different branches. For example, the output of vlatest -b shows every branch, regardless of whether it's under active development. Vesta maintainers need a way to identify those branches which represent changes which need to be merged into the main line.
The branch-status Attribute
To solve this problem, we use the branch-status attribute. There are several recognized values for branch-status
- open
This branch is an area of active development and should, at some point in the future, be merged into the main line. This is the assumed value if the branch-status attribute is not set.
- closed
- This branch has been merged into the main line, and is therefore historical.
An example would be eval/66.unique_run_tool which was merged in eval/67.
- abandoned
- This branch has not been merged into the main line, and currently there are no plans to do so. Such a branch might represent an idea which was dropped in favor of another alternative, or changes which were needed during some debug effort but weren't suitable for inclusion in the main-line code.
An example would be repos/65.tail_gap.
- obsolete
This branch will not been merged into the main line, but there is further development for the same change in a newer branch. (This is similar to abandoned, but indicates that there is some other branch based on a later version of the trunk which contains further development of the same change.) An example would be repltools/16.mount which was continued in repltools/20.mount.
- independent
This branch is independent: there's nowhere to merge it back into. For example, the branches created by pkg2vesta represent different versions of the OS component being imported; they're not forks of a version history within Vesta, and it doesn't make sense to merge them back into anything else in the future. An example would be /vesta/beta.vestasys.org/platforms/linux/debian/i386/components/binutils/2.15-4. (Note that this branch has an old-version attribute even though it is independent.)
Scripts
There are several scripts which help with using the branch status tags:
list-branches.py : This will list branches within one or more directories in the repository. For example, this command will list all branches in /vesta/vestasys.org/basics and /vesta/vestasys.org/vesta:
list-branches.py /vesta/vestasys.org/basics /vesta/vestasys.org/vesta
With the "--status" command line option, you can ask for a listing of only branches with a particular status. The most commonly used one would be "--status open", but you could also do "--status abandoned".set-branch-status.py : This script is used to set the branch-status attribute. You can pass it a specific branch to set the status of:
set-branch-status.py /vesta/vestasys.org/vesta/repos/66.VolRoot
Or a package or an entire hierarchy to update the status of every branch in it:set-branch-status.py /vesta/vestasys.org/vesta/repos/66.VolRoot
If you use it on many branches, you may want to add "--dont-repeat" which will cause it to skip any branches which already have a status set. It attempts to guess what the status should be (for example, by looking for a mention of the branch in the checking message of a later version in the enclosing package). It will explain such guesses and ask for confirmation, which you can decline. If you use this on a remote repository, please add "--update dev.vestasys.org" which will replicate each attribute change to dev.vestasys.org (so that others will see the status change).branch-status-repl.py : This script helps with propagatiung branch status changes to other repositories.
With "--destination host:port" (which can be given multiple times), it will replicate to the specified repositories.
With "--output file" it will write a file of replicator directives which you can use with vrepl.
With "--status open|closed|..." it will only include branches with the specified status.
On dev.vestasys.org, these scripts are all in /usr/local/bin.