Skip to content

Latest commit

 

History

History
198 lines (133 loc) · 6.56 KB

CONTRIBUTING.md

File metadata and controls

198 lines (133 loc) · 6.56 KB
Raw

Contributing to madlib-locale

Prerequisites

Setup

Clone this repository somewhere, switch to it, then:

git config commit.template ./.gitmessage
git checkout master
git checkout develop
git flow init -d
( cd ./.git/hooks && ln -s ../../.git-hooks/git-hook-on-npm-lockfile-change.sh post-checkout )
( cd ./.git/hooks && ln -s ../../.git-hooks/git-hook-on-npm-lockfile-change.sh post-merge )
npm run refresh

This will:

  • Set up a helpful reminder of how to make a good commit message. If you adhere to this, then a detailed, meaningful CHANGELOG can be constructed automatically;
  • Ensure you have local master and develop branches tracking their respective remote counterparts;
  • Set up the git flow branching model with default branch names;
  • Set up two git hooks to ensure that your node_modules will be synced with the package-lock.json dependency tree definition whenever a git merge or -checkout causes it to change;
  • Install all required dependencies, pruned and deduplicated;

Build

Most of the time you just want to invoke

grunt

This will build you the lib and doc artifacts into ./dist, ready for publication.

Test

Commit

Branching Model

This project uses git flow. Here's a quick cheat sheet.

Commit Message Format Discipline

This project uses conventional-changelog/standard-version for automatic versioning and CHANGELOG management.

To make this work, please ensure that your commit messages adhere to the Commit Message Format. Setting your git config to have the commit.template as referenced below will help you with a detailed reminder of how to do this on every git commit.

git config commit.template ./.gitmessage

Release / Hotfix

The steps layed out here are for the greater part oriented towards doing a regular release. To do a hotfix release instead, just write hotfix wherever (and everywhere) any of the steps below say release.

  • Ensure that you're up to scratch:

    git checkout master
git pull
git checkout develop
git pull

  • Determine what your next semver <version> should be:

    • For a regular release this should be based on the changes already in develop since the previous release or hotfix.
    • For a hotfix release this should be based on the changes you envision doing for this hotfix; but if you foresee it being anything other than a patch-level bump, you should probably reconsider wether this should really be a hotfix.
    version="<version>"

  • Create and checkout a release/v<version> branch off of develop:

    git flow release start "v${version}"

  • Push this branch upstream.

    git push --set-upstream origin "release/v${version}"

  • If this is a hotfix, now is a good time to first go and code the hotfix changes; If this is a regular release, just move on to the next step.

    As soon as the hotfix is ready and tested, it's time to move on the next step too.

  • Let the usual acceptance process take its course. If any changes are needed, code them in, test, rinse & repeat the previous step until everything is indeed accepted.

  • Bump the package's .version, update the CHANGELOG, commit these, and tag the commit as v<version>:

    npm run release

    or

    npm run hotfix

  • If all is well, this new .version should be identical to your intended <version>:

    jq ".version == \"${version}\"" package.json

    If this is not the case, then either your assumptions about what changed are wrong, or (at least) one of your commits did not adhere to the Commit Message Format Discipline; Abort the release, and sort it out first.

  • Ensure the npm run release commit and tag are pushed upstream too:

    git push --follow-tags

    This will also ensure that the git flow release finish ... below will be able to delete the release branch without error.

  • Merge release/v<version> back into both develop and master, checkout develop and delete release/v<version>:

    git flow release finish -n "v${version}"

    Note that contrary to vanilla git flow, the merge commit into master will not have been tagged (that's what the -n was for). This is done because npm run release has already tagged its own commit.

    I believe that in practice, this won't make a difference for the use of git flow; and ensuring it's done the other way round instead would render the use of conventional-changelog impossible.

  • Delete release/v<version> upstream too:

    git push origin --delete "release/v${version}"

  • Finally, ensure that all other affected branches are pushed upstream:

    git push origin master
git push origin develop

Publish

To NPM

git checkout v<version>
npm publish
git checkout develop

On GitHub

git push --follow-tags --all
  • Go to https://github.com/marviq/madlib-locale/releases;
  • Click the Draft a new release button;
  • Select the appropriate v<version> tag from the dropdown menu;
  • You could enter a title and some release notes here; at the very least include a link to the corresponding section in the CHANGELOG as: 
    [Change log](CHANGELOG.md# ... )
  • Click the Publish release button;