Clone wiki

NBTParse / Branching strategy

NBTParse's branching strategy is loosely based on standard branching.

In general, every open branch head is bookmarked to make the repository easier to navigate. Closed heads are not bookmarked, since there's no new development taking place there.

Most new development takes place on the default branch. The "canonical" head of the default branch is bookmarked @. Informally, this is the trunk, master branch, or whatever terminology you prefer. Mercurial updates to this bookmark automatically when cloning. Because of this, it's important to keep the bookmark up-to-date. Remember to manually advance it after doing a rebase or other history modification, if necessary. Failing to update the bookmark is tantamount to creating a new head.

The version number in nbtparse/__version__.txt is the version number of the next major release, followed by .dev0 to indicate a trunk snapshot. When merging, it may be necessary to revert changes to this file before committing. The .dev0 suffix is recognized by the Jenkins script, and replaced with .devN where N is the build number. This means that the dev series is discontinuous, but that doesn't matter so long as version numbers increase monotonically.

Releases are on branches with names like release-1.2.0, for suitable values of 1 and 2. The last digit is always zero, because patch releases don't get a new branch. Individually released commits have tags such as version-1.2.3, and are bookmarked version-stable or version-unstable to track the latest stable and unstable releases respectively. The head of the latest open release branch (if any) is bookmarked release-unstable; this bookmark always points to a head, just like @. Once NBTParse hits stable, bookmarks named release-stable-new and release-stable-old will also exist and serve analogous roles. Tag commits are preferably made on the trunk to simplify merging.

The above rules might be slightly difficult to follow. In general, things beginning with release- track an entire line of development, while version- items track individual commits. A numerical version number always refers to the same release or version, while a term like "stable" or "unstable" will change its meaning over time. Here's a table:

What are we tracking? Permanently Temporarily
One commit version-1.2.3 tags version-stable, version-unstable bookmarks
Entire branch release-1.2.0 branches release-unstable etc. bookmarks

No other named branches exist. Commits on nonstandard branches are stripped with extreme prejudice. All other branching is done with bookmarks, usually on the default branch. Nonstandard tags are similarly unused, though local tags mitigate this considerably. Both of these restrictions may be waived by the repository owner as needed.

There are no restrictions on bookmark names, except that publicly-visible bookmarks should not begin with local-. That prefix is reserved for local bookmarks (i.e. bookmarks which are not pushed to public repositories). In general, bookmarks should have reasonably understandable names, usually in all lowercase and separated by dashes.

For historical reasons, the extremely outdated 0.1.0 release lacks a version tag. It is not immediately apparent which commit was uploaded to PyPI and distributed as 0.1.0, so this should not be "fixed."