diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index afe55080f0..fd285afe6b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,49 +1,64 @@ -Hi collaborator! +Hi (future) collaborator! -We use **pull request** based approach to development. +**tl;dr;** +- submit pull requests to develop branch +- use conventional changelog commit style messages +- squash your commits +- have fun -**Have a fix or a new feature**? Search for corresponding issues first then -create a new one. + + +**Table of Contents** + +- [Where to start?](#where-to-start) +- [New API proposal](#new-api-proposal) +- [How to create issues](#how-to-create-issues) +- [Development workflow](#development-workflow) +- [Adding/Updating a package](#addingupdating-a-package) +- [Removing a package](#removing-a-package) +- [Commit message guidelines](#commit-message-guidelines) + - [Revert](#revert) + - [Type](#type) + - [Scope](#scope) + - [Subject](#subject) + - [Body](#body) + - [Footer](#footer) +- [Stash your commits](#stash-your-commits) +- [When are issues closed?](#when-are-issues-closed) +- [Milestones](#milestones) +- [Releasing](#releasing) + - [Beta releases](#beta-releases) +- [Hotfixes](#hotfixes) + - [Releasing hotfixes](#releasing-hotfixes) + + + +# Where to start? + +Have a fix or a new feature? [Search for corresponding issues](https://github.com/algolia/instantsearch.js/issues) first then create a new one. + +Always check the status of the [develop branch](https://github.com/algolia/instantsearch.js/tree/develop) for the freshest code. + +Always submit pull requests to the develop branch. + +**Wanna help us?** All issues belonging to the [`next` milestone](https://github.com/algolia/instantsearch.js/milestones/next) can be worked on. + +# New API proposal If you have a new **API proposal** or change, create an issue describing it precisely: -- JavaScript example +- JavaScript API example - Resulting DOM/effect Here's an example: [New widget: hitsPerPageSelector (#331)](https://github.com/algolia/instantsearch.js/issues/331). -# Workflow - -Most of our work should be based on issues. So that we are sure to have at least two or three people that agreed we needed to change something. - -Then, when you are ready: -- **assign** the issue to yourself, change the label to `in progress`. You can use the [waffle.io board](https://waffle.io/algolia/instantsearch.js/join). -- **create a branch** starting from the **develop** branch, name it like feat/blabla, fix/blabla, refactor/blabla -- see the [development workflow](#development-workflow) -- use our [commit message guidelines](#commit-message-guidelines) to provide a meaningful commit message: it will be inserted into the changelog automatically -- add a [#fix #issue](https://help.github.com/articles/closing-issues-via-commit-messages/) when relevant, in the commit body -- **submit** your pull request to the develop branch -- Add either `do not merge` or `ready for review` labels given your context -- wait for **review** -- do the necessary changes and add more commits -- once you are done, [squash](http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html) your commits to avoid things like "fix dangling comma in bro.js", "fix after review" - - example: - - `feat(widget): new feature blabla..` - - `refactor new feature blablabla...` (bad, not following our [commit message guidelines](#commit-message-guidelines) - - **both commits should be squashed* in a single commit: `feat(widget) ..` -- when **updating** your feature branch on develop, **always use rebase instead of merge** - -# When to close issues? +# How to write issues -Once the fix is done, having the fix in `develop` is not sufficient, it needs to be part of a release for us to close the issue. +Start with some context, when and/or where you encountered the issue. -So that you never ask yourself "Is this released?". - -Instead of closing the issue, you can just add the ` ✔ to be released` label. +Since instantsearch.js is a UI library, if your issue is UI related then adding a screenshot or (better) a GIF will make your issue a lot easier to understand. # Development workflow -Join our [waffle.io board](https://waffle.io/algolia/instantsearch.js/join)! - Rapidly iterate with our example app: ```sh @@ -57,14 +72,14 @@ Run the tests and lint: npm test ``` -## Adding/Updating a package +# Adding/Updating a package ```sh npm install package --save[-dev] npm run shrinkwrap ``` -## Removing a package +# Removing a package ```sh npm remove package --save[-dev] @@ -84,7 +99,7 @@ Here are the rules to write commit messages, they are the same than [angular/ang Each commit message consists of a **header**, a **body** and a **footer**. The header has a special format that includes a **type**, a **scope** and a **subject**: -``` +```text (): @@ -135,18 +150,63 @@ reference GitHub issues that this commit **Closes**. **Breaking Changes** should start with the word `BREAKING CHANGE:` with a space or two newlines. The rest of the commit message is then used for this. +# Stash your commits + +Once you are done with a fix or feature and the review was done, [squash](http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html) your commits to avoid things like "fix dangling comma in bro.js", "fix after review" + +Example: + - `feat(widget): new feature blabla..` + - `refactor new feature blablabla...` + - `fix after review ...` + - **both commits should be squashed* in a single commit: `feat(widget) ..` + +# When are issues closed? + +Once the a fix is done, having the fix in the `develop` branch is not sufficient, it needs to be part of a release for us to close the issue. + +So that you never ask yourself "Is this released?". + +Instead of closing the issue, we willat add a ` ✔ to be released` label. + # Milestones -- `next` => Ideas, questions, refactors, bugs that were discuseed, turned into clear actions by the maintainers -- `x.x.x` => selected `next` actions to be done in a release +- `next` => Ideas, questions, refactors, bugs that were discuseed, turned into clear actions by the maintainers. You can work on this. +- `x.x.x` => selected `next` actions to be done in a release. You can work on this. - no milestone => Still need investigation / discussion -# Labels +# Releasing + +If you are a maintainer, you can release. + +We use [semver](http://semver-ftw.org/). + +You must be on the master branch. + +```sh +npm run release +``` + +## Beta releases + +You must be on the develop branch. -- `needs api proposal` good change or addition idea. Now in need of a clear API proposal -- `new widget` new widget idea -- `ready` change accepted and can be done by anyone -- `in progress` you are working on it -- `question` anything that's not an accepted bug/new feature -- `do not merge` still working on a pull request, you want feedback but it's not finished -- `✔ to be released` corresponding pull request was merged. Now waiting for a release before closing the issue +```sh +npm run beta-release +``` + +# Hotfixes + +All our work is done on the develop branch but it could be necessary to push a hotfix to the master +branch and do a patch release. To fix a very important bug. + +For this, you should: +- add `HOTFIX` to the commit message **body** +- submit your pull request to the master branch + +## Releasing hotfixes + +You must be on the master branch. + +```sh +HOTFIX=1 npm run release +``` diff --git a/package.json b/package.json index 709c05f704..ce3dc1d0dd 100644 --- a/package.json +++ b/package.json @@ -8,7 +8,7 @@ "build": "./scripts/build.sh", "dev": "./scripts/dev.sh", "dev:docs": "./scripts/dev-docs.sh", - "doctoc": "doctoc --maxlevel 3 README.md", + "doctoc": "doctoc --maxlevel 3 README.md CONTRIBUTING.md", "jsdoc:widget": "babel-node ./scripts/doc/gen-widget-doc.js", "gh-pages": "./scripts/gh-pages.sh", "lint": "eslint . --quiet --no-color && sass-lint --verbose", diff --git a/scripts/release-beta.sh b/scripts/release-beta.sh index c6af8a980c..6e9f7396f8 100755 --- a/scripts/release-beta.sh +++ b/scripts/release-beta.sh @@ -66,7 +66,7 @@ VERSION=$newVersion babel-node ./scripts/bump-package-version.js NODE_ENV=production VERSION=$newVersion npm run build # regenerate readme TOC -printf "\n\nBeta release: generate README.mc TOC" +printf "\n\nBeta release: generate TOCS" npm run doctoc # regenerate widgets jsdoc diff --git a/scripts/release.sh b/scripts/release.sh index 192fe800ee..659c6ea9ec 100755 --- a/scripts/release.sh +++ b/scripts/release.sh @@ -1,5 +1,7 @@ #!/usr/bin/env bash +[ -z $HOTFIX ] && HOTFIX='0' + set -e # exit when error if [[ -n $(npm owner add `npm whoami`) ]]; then @@ -22,9 +24,11 @@ printf "\n\nRelease: update working tree" git pull origin master git fetch origin --tags -printf "\n\nRelease: merge develop branch" -git fetch origin develop -git merge origin/develop +if [ $HOTFIX == '0' ]; then + printf "\n\nRelease: merge develop branch" + git fetch origin develop + git merge origin/develop +fi printf "Release: npm install" npm install @@ -59,7 +63,7 @@ changelog=`conventional-changelog -p angular` conventional-changelog -p angular -i CHANGELOG.md -w # regenerate readme TOC -printf "\n\nRelease: generate README.md TOC" +printf "\n\nRelease: generate TOCS" npm run doctoc # regenerate widgets jsdoc diff --git a/scripts/validate-pr-done-on-develop.sh b/scripts/validate-pr-done-on-develop.sh index fa68f6b7f5..49b5bf9f16 100755 --- a/scripts/validate-pr-done-on-develop.sh +++ b/scripts/validate-pr-done-on-develop.sh @@ -2,12 +2,18 @@ set -e # exit when error +COMMIT_MSG=`git log --format=%B --no-merges -n 1` + if [ $TRAVIS_PULL_REQUEST == "false" ]; then - echo "No need to check pull request done on develop branch when not in a pull request" - exit 0 + MSG="No need to check pull request done on develop branch when not in a pull request" + EXIT=0 +elif [ $COMMIT_MSG == *"HOTFIX"* && $TRAVIS_BRANCH != 'master' ]; then + MSG="Hotfix must be submitted to master, good" + EXIT=1 +elif [ $TRAVIS_BRANCH != 'develop' ]; then + MSG="Pull request must be done on develop branch" + EXIT=1 fi -if [ $TRAVIS_BRANCH != 'develop' ]; then - echo "Pull request must be done on develop branch" - exit 1 -fi +echo $MSG; +exit $EXIT;