Merge Policies
These are some guidelines for handling branches and merging them back in to the trunk. While these guidelines were developed for the core Enzo developers, they apply to the repository in general.
Short-Term Branches
Short term branches are ones that address a specific need, like a bug fix, an isolated feature, or merging in some external code. The life-cycle for these branches is the following:
- Create the branch from the trunk.
- Make the necessary changes.
- Run the regression tests defined in lcatest, and fix any broken ones.
- Merge the branch back in to the trunk.
- Delete the branch.
Long-Term Branches
Long-term branches are either personal working copies (which are inevitably littered with printf calls), or branches undergoing extended development (usually additional physics). There are no hard and fast rules for the lives of these branches, but branch owners are encouraged to routinely merge changes to the trunk in to their own branch. This helps to distribute bug fixes and new features, and makes future merges up easier.
When merging a long-term branch into the trunk, the owner has two choices:
- Create a temporary (i.e., short-term) branch from the trunk, merge the changes into the temporary branch, and then merge the temporary branch in to the trunk after testing.
- Merge down all of the recent changes from the trunk, make sure the long-term branch is passing the regression tests, and then merge directly back the trunk.
Which option to choose will depend on whether or not the entire branch is being merged. If only a few changes are going in to the trunk, then creating a temporary branch is probably the better decision.
Once a long-term branch has merged with the trunk, it is up to the owner whether or not to delete the branch.
Isolated Commits
If possible, try to isolate changes in to a single commit to the trunk. This makes merging bug fixes and features out the public trunk easier. In other words, first commit the bug fixes, then commit the new physics routines.
Testing
When committing to the trunk, developers are encouraged to submit new tests with any bug fixes or new features. These tests may implement a test problem, or may just show that an algorithm is implemented correctly. The importance of the test is proportional to the severity of the bug (e.g., it kills people), or the significance of the feature (e.g., it proves the existence of the ether).
