diff --git a/.github/PROCESS.md b/.github/PROCESS.md index 9c652108d2..ee3418ef8e 100644 --- a/.github/PROCESS.md +++ b/.github/PROCESS.md @@ -1,11 +1,12 @@ # Process -This document is to describe the internal process that the Ionic team uses for issue management and project planning. +This document is to describe the internal process that the Ionic team uses for issue management, project planning and the development workflow. ## Table of contents * [Project Boards](#project-boards) * [Managing Issues](#managing-issues) * [Workflow](#workflow) + * [Releasing](#releasing) ## Project Boards @@ -80,11 +81,71 @@ if there is no response within 30 days, the issue will be closed and locked. ## Workflow +### Overview + +![](https://user-images.githubusercontent.com/6577830/53817482-80e6c480-3f33-11e9-9e09-be8dcf840ef8.png) + We have two long-living branches: - `master`: completed features, bug fixes, refactors, chores - `stable`: the latest release +The overall flow: + +1. Feature, refactor, and bug fix branches are created from `master` +1. When a feature, refactor, or fix is complete it is merged into `master` +1. A release branch is created from `master` +1. When the release branch is done it is merged into `master` and `stable` +1. If an issue in `stable` is detected a hotfix branch is created from `stable` +1. Once the hotfix is complete it is merged to both `master` and `stable` +1. All branches should follow the syntax of `{type}-{details}` where `{type}` is the type of branch (`hotfix`, `release`, or one of the [commit types](https://github.com/ionic-team/ionic/blob/master/.github/CONTRIBUTING.md#commit-message-format)) and `{details}` is a few hyphen separated words explaining the branch + +### Stable and Master Branches + +#### Stable Branch + +Branches created from `stable`: + +The following branch should be merged back to **both** `master` and `stable`: + +- A `hotfix` branch (e.g. `hotfix-missing-export`): a bug fix that is fixing a regression or issue with a published release + +A `hotfix` branch should be the **only** branch that is created from stable. + +#### Master Branch + +Branches created from `master`: + +The following branches should be merged back to `master` via a pull request: + +1. A feature branch (e.g. `feat-desktop-support`): an addition to the API that is not a bug fix or regression fix +1. A bug fix branch (e.g. `fix-tab-color`): a bug fix that is not fixing a regression or issue with a published release +1. All other types listed in the [commit message types](https://github.com/ionic-team/ionic/blob/master/.github/CONTRIBUTING.md#commit-message-format): `docs`, `style`, `refactor`, `perf`, `test`, `chore` + +The following branch should be merged back to **both** `master` and `stable`: + +1. A `release` branch (e.g. `release-4.1.x`): contains all fixes and (optionally) features that are tested and should go into the release + + +### Feature Branches + +Each new feature should reside in its own branch, based on the `master` branch. When a feature is complete, it should go into a pull request that gets merged back into `master`. A pull request adding a feature should be approved by two team members. Features should never interact directly with `stable`. + + +### Release Branches + +Once `master` has acquired enough features for a release (or a predetermined release date is approaching), fork a release branch off of `master`. Creating this branch starts the next release cycle, so no new features can be added after this point - only bug fixes, documentation generation, and other release-oriented tasks should go in this branch. + +Once the release is ready to ship, it will get merged into `stable` and `master`, then the release branch will be deleted. It’s important to merge back into `master` because critical updates may have been added to the release branch and they need to be accessible to new features. This should be done in a pull request after review. + +See the [steps for releasing](#releasing) below for detailed information on how to publish a release. + + +### Hotfix Branches + +Maintenance or “hotfix” branches are used to quickly patch production releases. This is the only branch that should fork directly off of `stable`. As soon as the fix is complete, it should be merged into both `stable` and `master` (or the current release branch). + + ### Examples #### Making a Change @@ -111,7 +172,7 @@ We have two long-living branches: 1. Confirm squash and merge into `master`. -#### Merging Changes from `master` into your Branch +#### Updating from `master` 1. Pull the latest changes locally. 1. Merge the changes, fixing any conflicts. @@ -125,23 +186,6 @@ OR 1. Pull the merged changes locally. -#### Making a Release - -1. Freeze `master`. Only the person doing the release should be modifying `master`. -1. Follow the [Making a Change](#making-a-change) steps to prepare the release. - - - Run `npm run release.prepare` - - Version changes - - `CHANGELOG.MD` tweaks - -1. Create a PR to merge `master` into `stable`. -1. Click **Merge pull request**. Use the dropdown to select this option if necessary. This will preserve the commit history from `master` by creating a merge commit. - - Merge pull request button - -1. CI builds `stable`, performing the release. -1. Unfreeze `master`. - #### Hotfixes Hotfixes bypass `master` and should only be used for urgent fixes that can't wait for the next release to be ready. @@ -165,3 +209,24 @@ Hotfixes bypass `master` and should only be used for urgent fixes that can't wai 1. Click **Merge pull request**. Use the dropdown to select this option if necessary. Merge pull request button + + +## Releasing + +1. Create the release branch from `master`, for example: `release-4.1.0`. +1. Submit a pull request to merge the release branch into `stable`. +1. Verify all tests are passing, fix any bugs if needed and make sure no undesired commits are in. +1. Navigate to the root of the repository. +1. Run `npm i` if it hasn't already been done. +1. Run `npm run release.prepare` + - Select the version based on the type of commits and the [Ionic Versioning](https://ionicframework.com/docs/intro/versioning) + - After the process completes, verify the version number in all packages (`core`, `docs`, `angular`) + - Verify the changelog commits are accurate and follow the [proper format]((https://github.com/ionic-team/ionic/blob/master/.github/CONTRIBUTING.md#commit-message-format)) + - Commit these changes with the version number as the message, e.g. `git commit -m "4.1.0"` +1. Run `npm run release` +1. Click **Merge pull request**. Use the dropdown to select this option if necessary. + + Merge pull request button + +1. Rewrite the commit message to `merge release-4.1.0` with the proper release branch. +1. Create a pull request and merge the release branch back into `master` using the same commit format in the last step, to ensure any changes made on the release branch get added to future releases.