From c07a70a847a2d9ca971633b256790b891615f4ed Mon Sep 17 00:00:00 2001 From: Cassie Tarakajian Date: Thu, 21 May 2020 17:00:27 -0400 Subject: [PATCH 1/2] Update travis.yml with new branch names, add git flow to development and release guides --- .github/CONTRIBUTING.md | 40 +----------------------- .travis.yml | 4 +-- developer_docs/README.md | 1 + developer_docs/development.md | 58 +++++++++++++++++++++++++++++++++-- developer_docs/release.md | 11 +++++++ 5 files changed, 71 insertions(+), 43 deletions(-) create mode 100644 developer_docs/release.md diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index 4c8fe8b7..fc813e0c 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -15,8 +15,6 @@ Hello! We welcome community contributions to the p5.js Web Editor. Contributing - [Issue Search and Tagging](#issue-search-and-tagging) - [Beginning Work](#beginning-work) - [Contribution Guides](#contribution-guides) - - [Writing Commit Messages](#writing-commit-messages) - - [Tips](#tips) ## Code of Conduct @@ -62,45 +60,9 @@ If you feel like an issue is tagged incorrectly (e.g. it's low priority and you If you'd like to work on an issue, please comment on it to let the maintainers know, so that they can assign it to you. If someone else has already commented and taken up that issue, please refrain from working on it and submitting a PR without asking the maintainers as it leads to unnecessary duplication of effort. -Then, follow the [installation guide](https://github.com/processing/p5.js-web-editor/blob/master/developer_docs/installation.md) to get the project building and working on your computer. +Then, look at the [development guide](https://github.com/processing/p5.js-web-editor/blob/master/developer_docs/development.md) for instructions on how to install the project locally and follow the right development workflow. ### Contribution Guides * [https://guides.github.com/activities/hello-world/](https://guides.github.com/activities/hello-world/) * [https://guides.github.com/activities/forking/](https://guides.github.com/activities/forking/) - -## Writing Commit Messages - -Good commit messages serve at least three important purposes: - -* They speed up the reviewing process. -* They help us write good release notes. -* They help future maintainers understand your change and the reasons behind it. - -Structure your commit message like this: - - ``` - Short (50 chars or less) summary of changes ( involving Fixes #Issue-number keyword ) - - More detailed explanatory text, if necessary. Wrap it to about 72 - characters or so. In some contexts, the first line is treated as the - subject of an email and the rest of the text as the body. The blank - line separating the summary from the body is critical (unless you omit - the body entirely); tools like rebase can get confused if you run the - two together. - - Further paragraphs come after blank lines. - - - Bullet points are okay, too - - - Typically a hyphen or asterisk is used for the bullet, preceded by a - single space, with blank lines in between, but conventions vary here - ``` - -* Write the summary line and description of what you have done in the imperative mode, that is as if you were commanding someone. Start the line with "Fix", "Add", "Change" instead of "Fixed", "Added", "Changed". -* Always leave the second line blank. -* Be as descriptive as possible in the description. It helps reasoning about the intention of commits and gives more context about why changes happened. - -## Tips - -* If it seems difficult to summarize what your commit does, it may be because it includes several logical changes or bug fixes, and are better split up into several commits using `git add -p`. \ No newline at end of file diff --git a/.travis.yml b/.travis.yml index da57c24a..16704b6c 100644 --- a/.travis.yml +++ b/.travis.yml @@ -37,12 +37,12 @@ deploy: script: ./deploy.sh skip_cleanup: true on: - branch: master + branch: release - provider: script script: ./deploy_staging.sh skip_cleanup: true on: - branch: feature/public-api + branch: develop env: global: diff --git a/developer_docs/README.md b/developer_docs/README.md index 2ac1dbf1..7fbacfd6 100644 --- a/developer_docs/README.md +++ b/developer_docs/README.md @@ -7,6 +7,7 @@ This folder contains documents intended for developers of the p5.js Web Editor. * [Preparing a pull-request](preparing_a_pull_request.md) - Instructions for how to make a pull-request * [Accessibility Guidelines](accessibility.md) - Guidelines for writing code to create an accessible application * [Deployment](deployment.md) - A guide to production deployment, and all platforms that are being used. +* [Release](./release.md) - A guide to creating a production release. ## Documents to Create * Design Principles - reference [p5.js design principles](https://github.com/processing/p5.js/edit/master/contributor_docs/design_principles.md) diff --git a/developer_docs/development.md b/developer_docs/development.md index d379456b..bacd7f06 100644 --- a/developer_docs/development.md +++ b/developer_docs/development.md @@ -2,20 +2,74 @@ A guide for adding code to this project. +- [Development](#development) + - [Installation](#installation) + - [Development Workflow](#development-workflow) + - [Tests](#tests) + - [Writing Git Commit Messages](#writing-git-commit-messages) + - [Tips](#tips) + - [Design](#design) + - [Technologies Used](#technologies-used) + ## Installation -Follow the [installation guide](https://github.com/processing/p5.js-web-editor/blob/master/developer_docs/installation.md). +Follow the [installation guide](./installation.md). + +## Development Workflow +This project uses git-flow. For an in-depth overview of git-flow, read ["A successful Git branching model"](https://nvie.com/posts/a-successful-git-branching-model/). As a person contributing code but not creating production releases (this is most people!), here's what you need to know: +* The default branch is `develop`. All pull requests should be made to this branch. It should be stable, and all commits are visible at a staging sever. +* When working on a bug or feature, you should branch from the `develop` branch. When you're done, you should open a pull request from your feature branch to `develop`. +* The `release` branch is the live production branch, and is the code deployed to editor.p5js.org. Changes to this branch should be made carefully, and will be done using git tags. +* Emergency hotfix changes should be branched from `release` and merged via a pull request to `release`. After a PR is merged, then the commits can be merged to `develop`. + +See the [release guide](./release.md) for information about creating a release. ## Tests To run the test suite simply run `npm test` (after installing dependencies with `npm install`) A sample unit test could be found here: [Nav.test.jsx](../client/components/__test__/Nav.test.jsx). +## Writing Git Commit Messages + +Good commit messages serve at least three important purposes: + +* They speed up the reviewing process. +* They help us write good release notes. +* They help future maintainers understand your change and the reasons behind it. + +Structure your commit message like this: + + ``` + Short (50 chars or less) summary of changes ( involving Fixes #Issue-number keyword ) + + More detailed explanatory text, if necessary. Wrap it to about 72 + characters or so. In some contexts, the first line is treated as the + subject of an email and the rest of the text as the body. The blank + line separating the summary from the body is critical (unless you omit + the body entirely); tools like rebase can get confused if you run the + two together. + + Further paragraphs come after blank lines. + + - Bullet points are okay, too + + - Typically a hyphen or asterisk is used for the bullet, preceded by a + single space, with blank lines in between, but conventions vary here + ``` + +* Write the summary line and description of what you have done in the imperative mode, that is as if you were commanding someone. Start the line with "Fix", "Add", "Change" instead of "Fixed", "Added", "Changed". +* Always leave the second line blank. +* Be as descriptive as possible in the description. It helps reasoning about the intention of commits and gives more context about why changes happened. + +### Tips + +* If it seems difficult to summarize what your commit does, it may be because it includes several logical changes or bug fixes, and are better split up into several commits using `git add -p`. + ## Design - [Style Guide/Design System on Figma](https://github.com/processing/p5.js-web-editor/labels/good%20medium%20issues) - [Latest Design on Figma](https://www.figma.com/file/5KychMUfHlq97H0uDsen1U/p5-web-editor-2017.p.copy?node-id=0%3A1). Note that the current design on the website has diverged, are parts of this design will not be implemented, but it is still helpful to have around for reference. - [Mobile Designs](https://www.figma.com/file/5KychMUfHlq97H0uDsen1U/p5-web-editor-2017.p.copy?node-id=0%3A2529), [Responsive Designs](https://www.figma.com/file/5KychMUfHlq97H0uDsen1U/p5-web-editor-2017.p.copy?node-id=0%3A3292) -# Technologies Used +## Technologies Used **MERN stack** - MongoDB, Express, React/Redux, and Node. diff --git a/developer_docs/release.md b/developer_docs/release.md new file mode 100644 index 00000000..42e86c34 --- /dev/null +++ b/developer_docs/release.md @@ -0,0 +1,11 @@ +# Release + +A guide for creating a release. + +## Background +This project release guide is based on +* [git-flow](https://nvie.com/posts/a-successful-git-branching-model/) +* [Semantic Versioning (semver)](https://semver.org/) +* [npm-version](https://docs.npmjs.com/cli/version) + +## Steps From cd4f585ea76eb48d7cc734c846ce512efb34165a Mon Sep 17 00:00:00 2001 From: Cassie Tarakajian Date: Thu, 21 May 2020 17:43:58 -0400 Subject: [PATCH 2/2] Update release guide with git flow steps, update Travis deployment to use git tag --- .travis.yml | 1 + deploy.sh | 4 ++-- developer_docs/development.md | 5 ++++- developer_docs/release.md | 13 +++++++++++++ 4 files changed, 20 insertions(+), 3 deletions(-) diff --git a/.travis.yml b/.travis.yml index 16704b6c..16287434 100644 --- a/.travis.yml +++ b/.travis.yml @@ -38,6 +38,7 @@ deploy: skip_cleanup: true on: branch: release + tags: true - provider: script script: ./deploy_staging.sh skip_cleanup: true diff --git a/deploy.sh b/deploy.sh index 9ef39a8b..2dc71273 100755 --- a/deploy.sh +++ b/deploy.sh @@ -4,9 +4,9 @@ set -e docker-compose build --no-cache docker login -u="$DOCKER_USERNAME" -p="$DOCKER_PASSWORD" -docker tag $APP_IMAGE_NAME $DOCKER_USERNAME/$DOCKER_REPOSITORY:$TRAVIS_COMMIT +docker tag $APP_IMAGE_NAME $DOCKER_USERNAME/$DOCKER_REPOSITORY:$TRAVIS_TAG docker tag $APP_IMAGE_NAME $DOCKER_USERNAME/$DOCKER_REPOSITORY:latest -docker push $DOCKER_USERNAME/$DOCKER_REPOSITORY:$TRAVIS_COMMIT +docker push $DOCKER_USERNAME/$DOCKER_REPOSITORY:$TRAVIS_TAG docker push $DOCKER_USERNAME/$DOCKER_REPOSITORY:latest echo $GCLOUD_SERVICE_KEY_PRD | base64 --decode -i > ${HOME}/gcloud-service-key.json diff --git a/developer_docs/development.md b/developer_docs/development.md index bacd7f06..23780c6d 100644 --- a/developer_docs/development.md +++ b/developer_docs/development.md @@ -15,7 +15,10 @@ A guide for adding code to this project. Follow the [installation guide](./installation.md). ## Development Workflow -This project uses git-flow. For an in-depth overview of git-flow, read ["A successful Git branching model"](https://nvie.com/posts/a-successful-git-branching-model/). As a person contributing code but not creating production releases (this is most people!), here's what you need to know: +* This project uses git-flow. For an in-depth overview of git-flow, read ["A successful Git branching model"](https://nvie.com/posts/a-successful-git-branching-model/). +* [Let's stop saying Master/Slave](https://medium.com/@mikebroberts/let-s-stop-saying-master-slave-10f1d1bf34df) + +As a person contributing code but not creating production releases (this is most people!), here's what you need to know: * The default branch is `develop`. All pull requests should be made to this branch. It should be stable, and all commits are visible at a staging sever. * When working on a bug or feature, you should branch from the `develop` branch. When you're done, you should open a pull request from your feature branch to `develop`. * The `release` branch is the live production branch, and is the code deployed to editor.p5js.org. Changes to this branch should be made carefully, and will be done using git tags. diff --git a/developer_docs/release.md b/developer_docs/release.md index 42e86c34..87ced793 100644 --- a/developer_docs/release.md +++ b/developer_docs/release.md @@ -7,5 +7,18 @@ This project release guide is based on * [git-flow](https://nvie.com/posts/a-successful-git-branching-model/) * [Semantic Versioning (semver)](https://semver.org/) * [npm-version](https://docs.npmjs.com/cli/version) +* [Let's stop saying Master/Slave](https://medium.com/@mikebroberts/let-s-stop-saying-master-slave-10f1d1bf34df) ## Steps +1. `$ git checkout develop` +2. `$ git checkout -b release-` +3. Do all of the release branch testing necessary. This could be as simple as running `npm test:ci`, or it could take user testing over a few days. +4. `$ git checkout release` +5. `$ git merge --no-ff release-` +6. `$ npm version ` (see [npm-version](https://docs.npmjs.com/cli/version) for valid values of ). +7. `$ git push && git push --tags` +8. `$ git checkout develop` +9. `$ git merge --no-ff release-` + +Travis CI will automatically deploy the release to production, as well as push a production tagged Docker image to DockerHub. +