Instructions for Maintainers

Merging Pull Requests

Also applies to changes without PRs.

Ensure origin looks like this in .git/config. The key element here is the second fetch statement

[remote "origin"]
  url = [email protected]:dc-js/dc.js.git
  fetch = +refs/heads/*:refs/remotes/origin/*
  fetch = +refs/pull/*/head:refs/remotes/origin/pr/*

As of January 2015, we use the git-flow workflow to support two active versions at once. An excellent introduction is here: http://jeffkreeftmeijer.com/2010/why-arent-you-using-git-flow/

First, decide whether you will merge the change as a hotfix (to master), or as a feature (to develop).

General build steps

Follow these rigorously when tagging a new version! Follow them even if you're not.

0. npm update (update node modules that may be pulled into web/)
1. Change version in package.json (if doing a hotfix)
2. grunt docs
3. grunt update-stock-example (if changing the version or making other changes you know will affect the stock example)
4. grunt test && grunt test-browserify
5. Check in artifacts
6. Add entries to Changelog.md

Publish to the web (after each merge to develop, i.e. finishing a hotfix or feature)

4. git push
5. Wait for Travis tests to cycle!
6. git diff origin/gh-pages master:web (review changes before site deployment)
7. grunt web

Merge a hotfix

Every hotfix gets merged to master, tagged, and merged to develop. Usually the tag will be a version number, but names are also acceptable if you don't plan to make a release. It's not recommended to have multiple hotfix branches open at once, and not a good idea to publish/push hotfix branches to GitHub.

git flow hotfix start <tag>
git merge origin/pr/###

Fix stuff, make sure there are tests and (if relevant) that the tests fail before the PR.

git flow hotfix finish <tag>

This will do all the merges, and you may have to work the mergetool a few times.

Ugh, merge conflicts!

Unfortunately, you will get a bunch of merge conflicts at this point due to all the artifacts!

Get a list of conflicts with git status

First, look for the conflicts that are not artifacts. Build artifacts include dc.*js*, web/docs/*, web/js/*. Ignore those for now.

For any that you want to keep as it was, for example (usually), package.json:

git checkout --ours package.json
git add package.json

http://gitready.com/advanced/2009/02/25/keep-either-file-in-merge-conflicts.html

For any that you want to merge, for example (usually), Changelog.md:

git mergetool Changelog.md

Now generate all the artifacts

grunt
grunt docs
grunt update-stock-example

Add all of them (warning: this is powerful, you should test again before to make sure everything has been generated):

git add dc.*js web/docs/*.* web/js/* regression/rendered-stock-fixture.html

Push the changes

git checkout develop; git push
git checkout master; git push
git push --tags

Now: wait for Travis to validate the changes. If it fails, you will have to tag a new version, so it's important not to publish to npm until we know it's good.

To avoid this uncertainty, test in various browsers using

grunt server

and navigate to http://127.0.0.1:8888/spec/

Finally, if Travis says it's okay:

npm publish

cdnjs will pick it up automatically.

Merge a feature

Feature branch names should be short but descriptive. It's acceptable to have many feature branches open at once (as long as you're happy with your mergetool).

develop can always be merged to a feature branch.

When a feature is ready, finish it to merge it back to develop. Feature branches can be published (pushed) back to GitHub.

git flow feature start <tag>
git merge origin/pr/###

Fix stuff, make sure there are tests and (if relevant) that the tests fail before the PR.

git flow feature finish <tag>

Merges to develop

git push