Mercurial Best Practices

Mercurial Best Practices

Sunset Bay, Oregon.

Just a draft of a some 'best practices' we should consider when we start using Mercurial. This is not gospel, not official, not perfect, just a basis for discussion.

Also, some of these best practices might be enforceable via Mercurial hooks, and that seems like a good idea to me, but I haven't tried hooks like this yet.

Proposed Mercurial Best Practices (or Best Intentions?):

  • Integration repositories should never have an 'hg pull' operation done to them. An integration repository is any repository that is the target of an 'hg push', and changes to integration repositories should only come in via a 'hg push'. By default, 'hg push' will not let you push multiple heads. The best way to update an integration repository is to clone a separate 'merge' repository instance, pull the changes from the integration parent into this 'merge' clone, perform the appropriate testing to verify the merge is acceptable, and then push the resulting merged changesets into the integration repository. This protects all other team members by providing a clean repository to pull from and to push to.
  • Integration repositories should NEVER have multiple heads. Separate integration repositories should be used for separate development efforts or source branches.
  • The 'hg status' command should never list files that should be ignored, e.g. the file .hgignore must be defined to ignore all files that should not be managed in the repository.
  • The creation of a changeset ('hg commit') should be done when the change is in a final state and ready to be 'committed' to a repository. Changesets should not be created for preliminary changes or experimental changes. Consider using patches for changes that have not been reviewed, built, and at least had preliminary testing done. Multiple changesets that have never left the nest (never pushed or pulled), could be merged together via a fresh clone, copy of the working set files, and a fresh changeset created in the clone. I'd recommend delaying the 'hg commit' until you are relatively sure that you are done rather than hassle with merging changesets.
  • The first line of a changeset comment should be a standalone description of the changeset and be less than 65 characters, e.g. "Changes for: 8140072 and 1466620", "Sync changes, w/details", or for a simple one bug fix, just "Fixed NNNNNNN: Synopsis".
  • The non-merge changeset comment must include at least one bugid, and the comment should include at least one line per bug of the form:
      Fixed NNNNNNN: Synopsis
  • Each changeset should fix one or more bugs completely. Partial fixes should be rare, and should use the line:
      Partial NNNNNNN: Synopsis
  • In the rare case where an additional changeset is needed for a fix or feature the changeset comments should repeat the line:
      Fixed NNNNNNN: Synopsis
    as needed.
  • The comments should not include: login names, user names, copyright notices, email addresses, ads, spam, jokes, or foul language. These comments will be publicly visible and should comment the changeset in a professional manner.
  • The comments should be in English, using only the simple ASCII character set.
  • The comments should not include code snippets and should be kept as brief as possible, or be of a size appropriate to the changes it represents. Major features may require a more detailed changeset comment, but the changeset comments should not be used as documentation on a feature, rather it should describe why the changes were needed to support that feature.

Ideally, Mercurial changesets should ultimately provide a complete bundle for a fix or feature, I know there may be exceptions to the rule, but if we set down the rules early we can start creating clean and self-documenting changesets.

Let me know what you think.

-kto

Comments:

Post a Comment:
Comments are closed for this entry.
About

Various blogs on JDK development procedures, including building, build infrastructure, testing, and source maintenance.

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today