duktape/doc/git-conventions.rst

===============
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