Git conventions

Repositories

The main development repository is hosted on GitHub:

• https://github.com/svaarala/duktape

The duktape.org website is also part of the repository. Up to Duktape 0.12.0 the release binaries were also stored in the Duktape repo. For Duktape 1.0.0 and after the convention is changed to use external binaries; see the Releases section below. The upside of keeping the website in the same repo is that old documentation matching the current checkout is always available.

There's a separate repo for release binaries, so that binaries are reliably available but don't bloat the main repository:

• https://github.com/svaarala/duktape-releases

This repo also provides unpacked release files as tags for convenience.

Issue tracking

Issues are tracked in GitHub, i.e. outside the repository itself.

Releases

Release versioning follows semantic versioning; for details, see:

• http://duktape.org/guide.html#versioning

Release artifacts:

• A tag is created for the release (e.g. v1.0.4) in the main repo.

• A GitHub release is also created for convenience with the end user tar.xz attached to the release:

  • https://github.com/blog/1547-release-your-software

  The release title should be the same as the release description in the tag.

• The release tar.xz is added to the duktape-releases repo:

  • https://github.com/svaarala/duktape-releases

• The unpacked tar.xz is also added as a tag (on an independent branch) on the duktape-releases repo for convenience. The tag is named vN.N.N. The independent branch used to create the tag is not kept. See release-checklist.rst for detailed commands.

  • http://stackoverflow.com/questions/15034390/how-to-create-a-new-and-empty-root-branch
  • http://stackoverflow.com/questions/9034540/how-to-create-a-git-branch-that-is-independent-of-the-master-branch

• The releases are also available from http://duktape.org/.

Branch and tag naming

Development branches:

• master: Churn branch with active development, kept close to release quality at all times; unstable features are developed in feature branches.
• frob-xyz-tweaks, add-missing-docs, etc.: Relatively short lived branches for developing a particular feature; may be rebased, commits may be squashed, etc. Merged into master when code works, documentation has been updated, etc., and then deleted. There is no fixed branch naming but avoid fix- and bug- prefixes.
• fix-xxx: Short lived bug fix branch, otherwise similar to a feature branch. The branch name should begin with fix- to differentiate it from feature development.

Maintenance branches:

• vN.N-maintenance: Maintenance branch for a release, which is used to backport fixes. For example, v1.0-maintenance would be used to release all v1.0.N releases. A maintenance branch is branched off master just before an initial zero patch level release. Release prepping should be done in master so that there's no need to backport release notes and such.
• vN-maintenance: Maintenance branch for a certain major version (e.g. 1.x) which is created when master moves on for development of the next major version.

Release tags:

• vN.N.N: Release tags. All releases are created from a maintenance branch, even the zero patch level version.

Other conventions:

• Rejected branches which may be needed later are tagged so that they don't clutter up the branch list. Use an annotated tag:

  $ git tag -a -m "archive rejected xyz" -s archive/rejected-xyz xyz-feature
  $ git branch -D xyz-feature
  

Merging

All features and fixes should be developed in separate branches and merged to master.

Before merging:

• Ensure test cases pass and broken test cases are fixed to match possible new output.
• Ensure documentation is up-to-date, including both internal and external documentation.

Branches should be merged with --no-ff to avoid fast forward merges:

$ git checkout -b frob-xyz-tweaks
# develop...
$ git checkout master
$ git merge --no-ff frob-xyz-tweaks
$ git branch -d frob-xyz-tweaks

Making fixes to maintenance branches

• Make fix to master first through a fix branch. This includes code changes, testcase changes, release note update.

• Check out maintenance branch (e.g. v1.0-maintenance), and git cherry pick fix commits from master. Cherry pick code changes and testcase changes where appropriate (to allow the fix to be tested). Don't update release note in the branch: release notes are only kept up-to-date in master.

  If a lot of commits need to be cherry picked, create a branch and merge to maintenance branch.

• Git cherry picking:

  • http://sleeplessgeek.blogspot.fi/2011/03/using-git-cherry-pick.html

• Basically:

  $ git cherry-pick <commit>
  

Commit messages

Merges to master branch must have clean commit messages. Merge commit should retain the default merge heading which should be followed by a descriptive paragraph similar to what the release note updates are. This makes the merge commits useful for getting an overview of what changes have been made and why.

Commit messages should follow these guidelines:

• Capitalized title line at most 50 characters long, no trailing period. This works best with GitHub and is also a common convention.
• Beneath that use normal sentence structure, bullet lists etc. are OK. No particular format for this part now.
• GitHub compatible messages are nice:
  • https://github.com/blog/926-shiny-new-commit-styles
  • http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html