From 045e95d1224c05c7b12c25a7fc2304f695519a40 Mon Sep 17 00:00:00 2001 From: Ches Martin Date: Fri, 14 Feb 2020 05:49:20 +0700 Subject: [PATCH 1/3] Document release steps Separate what concerns contributors versus what concerns maintainers. --- docs/contributing/contributing.md | 41 +++++++++++++++++++++++-------- 1 file changed, 31 insertions(+), 10 deletions(-) diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md index 0a32ae284a0..0d74826c3b6 100644 --- a/docs/contributing/contributing.md +++ b/docs/contributing/contributing.md @@ -526,17 +526,38 @@ And to format: $ make format-python ``` -## 4. Release process +## 4. Versioning policy and branch workflow -Feast uses [semantic versioning](https://semver.org/). +Feast uses [semantic versioning](https://semver.org/). As such, while it is still pre-1.0 breaking changes will happen in minor versions. + +Contributors are encouraged to understand our branch workflow described below, for choosing where to branch when making a change (and thus the merge base for a pull request). * Major and minor releases are cut from the `master` branch. -* Whenever a major or minor release is cut, a branch is created for that release. This is called a "release branch". For example if `0.3` is released from `master`, a branch named `v0.3-branch` is created. -* You can create a release branch via the GitHub UI. -* From this branch a git tag is created for the specific release, for example `v0.3.0`. -* Tagging a release will automatically build and push the relevant artifacts to their repositories or package managers \(docker images, Python wheels, etc\). -* A release branch should be substantially _feature complete_ with respect to the intended release. Code that is committed to `master` may be merged or cherry-picked on to a release branch, but code that is directly committed to the release branch should be solely applicable to that release \(and should not be committed back to master\). -* In general, unless you're committing code that only applies to the release stream \(for example, temporary hotfixes, backported security fixes, or image hashes\), you should commit to `master` and then merge or cherry-pick to the release branch. -* It is also important to update the [CHANGELOG.md](https://github.com/gojek/feast/blob/master/CHANGELOG.md) when submitting a new release. This can be in the same PR or a separate PR. -* Finally it is also important to create a [GitHub release](https://github.com/gojek/feast/releases) which includes a summary of important changes as well as any artifacts associated with that release. +* Each major and minor release has a long-lived maintenance branch, for example `v0.3-branch`. This is called a "release branch". +* From the release branches, patch version releases are tagged, for example `v0.3.0`. + +A release branch should be substantially _feature complete_ with respect to the intended release. Code that is committed to `master` may be merged or cherry-picked on to a release branch, but code that is directly committed to a release branch should be solely applicable to that release \(and should not be committed back to master\). + +In general, unless you're committing code that only applies to a particular release stream \(for example, temporary hotfixes, backported security fixes, or image hashes\), you should base changes from `master` and then merge or cherry-pick to the release branch. + +### 4.1 Release process + +For Feast maintainers, these are the concrete steps for making a new release. + +1. For a major or minor release, create and check out the release branch for the new stream, e.g. `v0.6-branch`. For a patch version, check out the stream's release branch. +1. In the root `pom.xml`, remove `-SNAPSHOT` from the `` property, and commit. +1. Push. For a new release branch, open a PR against master. +1. When CI passes, merge. (Remember _not_ to delete the new release branch). +1. Tag the merge commit with the release version, using a `v` prefix. Push the tag. +1. Bump to the next working version and append `-SNAPSHOT` in `pom.xml`. +1. Update the [CHANGELOG.md]: + + $ docker run -it --rm -e CHANGELOG_GITHUB_TOKEN="[Token]" -v "$(pwd)":/usr/local/src/your-app ferrarimarco/github-changelog-generator --user gojek --project feast + Get a token [according to the instructions][changelog gen token]. +1. Commit the POM and changelog, and open a PR. +1. Create a [GitHub release](https://github.com/gojek/feast/releases) which includes a summary of important changes as well as any artifacts associated with the release. + +When a tag that matches a Semantic Version string is pushed, CI will automatically build and push the relevant artifacts to their repositories or package managers \(docker images, Python wheels, etc\). JVM artifacts are promoted from Sonatype OSSRH to Maven Central, but it sometimes takes some time for them to be available. +[CHANGELOG.md]: https://github.com/gojek/feast/blob/master/CHANGELOG.md +[changelog gen token]: https://github.com/github-changelog-generator/github-changelog-generator#github-token From b3aa35e392ac1d4b2fa453916c72fc9f0a345de6 Mon Sep 17 00:00:00 2001 From: Willem Pienaar <6728866+woop@users.noreply.github.com> Date: Sat, 2 May 2020 09:54:12 +0800 Subject: [PATCH 2/3] Update release process with changelog guide --- docs/contributing/contributing.md | 39 +++++++++++++++++++++++++------ 1 file changed, 32 insertions(+), 7 deletions(-) diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md index 0d74826c3b6..8098d5477e3 100644 --- a/docs/contributing/contributing.md +++ b/docs/contributing/contributing.md @@ -545,19 +545,44 @@ In general, unless you're committing code that only applies to a particular rele For Feast maintainers, these are the concrete steps for making a new release. 1. For a major or minor release, create and check out the release branch for the new stream, e.g. `v0.6-branch`. For a patch version, check out the stream's release branch. +1. Update the [CHANGELOG.md]. See the [Creating a change log](#42-creating-a-change-log) guide. 1. In the root `pom.xml`, remove `-SNAPSHOT` from the `` property, and commit. 1. Push. For a new release branch, open a PR against master. 1. When CI passes, merge. (Remember _not_ to delete the new release branch). 1. Tag the merge commit with the release version, using a `v` prefix. Push the tag. 1. Bump to the next working version and append `-SNAPSHOT` in `pom.xml`. -1. Update the [CHANGELOG.md]: - - $ docker run -it --rm -e CHANGELOG_GITHUB_TOKEN="[Token]" -v "$(pwd)":/usr/local/src/your-app ferrarimarco/github-changelog-generator --user gojek --project feast - Get a token [according to the instructions][changelog gen token]. -1. Commit the POM and changelog, and open a PR. -1. Create a [GitHub release](https://github.com/gojek/feast/releases) which includes a summary of important changes as well as any artifacts associated with the release. +1. Commit the POM and open a PR. +1. Create a [GitHub release](https://github.com/gojek/feast/releases) which includes a summary of important changes as well as any artifacts associated with the release. Make sure to include the same change log as added in [CHANGELOG.md]. Use `Feast vX.Y.Z` as the title. +1. Create one final PR to the master branch and also update its [CHANGELOG.md]. When a tag that matches a Semantic Version string is pushed, CI will automatically build and push the relevant artifacts to their repositories or package managers \(docker images, Python wheels, etc\). JVM artifacts are promoted from Sonatype OSSRH to Maven Central, but it sometimes takes some time for them to be available. [CHANGELOG.md]: https://github.com/gojek/feast/blob/master/CHANGELOG.md -[changelog gen token]: https://github.com/github-changelog-generator/github-changelog-generator#github-token + +## 4.2 Creating a change log + +We use an [open source change log generator](https://hub.docker.com/r/ferrarimarco/github-changelog-generator/) to generate change logs. The process still requires a little bit of manual effort. +1. Create a GitHub token as [per these instructions ](https://github.com/github-changelog-generator/github-changelog-generator#github-token). The token is used as an input argument (`-t`) to the changelog generator. +2. The change log generator configuration below will look for unreleased changes on a specific branch. The branch will be `master` for a major/minor release, or a release branch (`v0.4-branch`) for a patch release. You will need to set the branch using the `--release-branch` argument. +3. You should also set the `--future-release` argument. This is the version you are releasing. The version can still be changed at a later date. +4. Update the arguments below and run the command to generate the change log to the console. +``` +docker run -it --rm ferrarimarco/github-changelog-generator \ +--user gojek \ +--project feast \ +--release-branch \ +--future-release \ +--unreleased-only \ +--no-issues \ +--bug-labels kind/bug \ +--enhancement-labels kind/feature \ +--breaking-labels compat/breaking \ +-t \ +--max-issues 1 \ +-o +``` +5. Review each change log item. + - Make sure that sentences are grammatically correct and well formatted (although we will try to enforce this at the PR review stage). + - Make sure that each item is categorized correctly. You will see the following categories: `Breaking changes`, `Implemented enhancements`, `Fixed bugs`, and `Merged pull requests`. Any unlabeled PRs will be found in `Merged pull requests`. It's important to make sure that any `breaking changes`, `enhancements`, or `bug fixes` are pulled up out of `merged pull requests` into the correct category. Housekeeping, tech debt clearing, infra changes, or refactoring do not count as `enhancements`. Only enhancements a user benefits from should be listed in that category. + - Make sure that the "Full Changelog" link is actually comparing the correct tags (normally your released version against the previously version). + - Make sure that release notes and breaking changes are present. From 863afdea0d81de680565dee4eb9b0a14644542bb Mon Sep 17 00:00:00 2001 From: Ches Martin Date: Tue, 5 May 2020 08:51:19 +0700 Subject: [PATCH 3/3] docs: Move release process updates into its new dedicated page On master we still have a monolithic `docs/contributing/contributing.md` _and_ redundant copies of some of the information in broken out pages (that have missed some useful updates to the monolith). Needs to get sorted out, but going ahead and moving release process to the dedicated page that now exists for it, in part to port easily to v0.4 docs where the monolith is gone. --- docs/contributing/contributing.md | 61 ------------------------- docs/contributing/release-process.md | 68 ++++++++++++++++++++++++---- 2 files changed, 58 insertions(+), 71 deletions(-) diff --git a/docs/contributing/contributing.md b/docs/contributing/contributing.md index 8098d5477e3..3a267dab93d 100644 --- a/docs/contributing/contributing.md +++ b/docs/contributing/contributing.md @@ -525,64 +525,3 @@ And to format: ```text $ make format-python ``` - -## 4. Versioning policy and branch workflow - -Feast uses [semantic versioning](https://semver.org/). As such, while it is still pre-1.0 breaking changes will happen in minor versions. - -Contributors are encouraged to understand our branch workflow described below, for choosing where to branch when making a change (and thus the merge base for a pull request). - -* Major and minor releases are cut from the `master` branch. -* Each major and minor release has a long-lived maintenance branch, for example `v0.3-branch`. This is called a "release branch". -* From the release branches, patch version releases are tagged, for example `v0.3.0`. - -A release branch should be substantially _feature complete_ with respect to the intended release. Code that is committed to `master` may be merged or cherry-picked on to a release branch, but code that is directly committed to a release branch should be solely applicable to that release \(and should not be committed back to master\). - -In general, unless you're committing code that only applies to a particular release stream \(for example, temporary hotfixes, backported security fixes, or image hashes\), you should base changes from `master` and then merge or cherry-pick to the release branch. - -### 4.1 Release process - -For Feast maintainers, these are the concrete steps for making a new release. - -1. For a major or minor release, create and check out the release branch for the new stream, e.g. `v0.6-branch`. For a patch version, check out the stream's release branch. -1. Update the [CHANGELOG.md]. See the [Creating a change log](#42-creating-a-change-log) guide. -1. In the root `pom.xml`, remove `-SNAPSHOT` from the `` property, and commit. -1. Push. For a new release branch, open a PR against master. -1. When CI passes, merge. (Remember _not_ to delete the new release branch). -1. Tag the merge commit with the release version, using a `v` prefix. Push the tag. -1. Bump to the next working version and append `-SNAPSHOT` in `pom.xml`. -1. Commit the POM and open a PR. -1. Create a [GitHub release](https://github.com/gojek/feast/releases) which includes a summary of important changes as well as any artifacts associated with the release. Make sure to include the same change log as added in [CHANGELOG.md]. Use `Feast vX.Y.Z` as the title. -1. Create one final PR to the master branch and also update its [CHANGELOG.md]. - -When a tag that matches a Semantic Version string is pushed, CI will automatically build and push the relevant artifacts to their repositories or package managers \(docker images, Python wheels, etc\). JVM artifacts are promoted from Sonatype OSSRH to Maven Central, but it sometimes takes some time for them to be available. - -[CHANGELOG.md]: https://github.com/gojek/feast/blob/master/CHANGELOG.md - -## 4.2 Creating a change log - -We use an [open source change log generator](https://hub.docker.com/r/ferrarimarco/github-changelog-generator/) to generate change logs. The process still requires a little bit of manual effort. -1. Create a GitHub token as [per these instructions ](https://github.com/github-changelog-generator/github-changelog-generator#github-token). The token is used as an input argument (`-t`) to the changelog generator. -2. The change log generator configuration below will look for unreleased changes on a specific branch. The branch will be `master` for a major/minor release, or a release branch (`v0.4-branch`) for a patch release. You will need to set the branch using the `--release-branch` argument. -3. You should also set the `--future-release` argument. This is the version you are releasing. The version can still be changed at a later date. -4. Update the arguments below and run the command to generate the change log to the console. -``` -docker run -it --rm ferrarimarco/github-changelog-generator \ ---user gojek \ ---project feast \ ---release-branch \ ---future-release \ ---unreleased-only \ ---no-issues \ ---bug-labels kind/bug \ ---enhancement-labels kind/feature \ ---breaking-labels compat/breaking \ --t \ ---max-issues 1 \ --o -``` -5. Review each change log item. - - Make sure that sentences are grammatically correct and well formatted (although we will try to enforce this at the PR review stage). - - Make sure that each item is categorized correctly. You will see the following categories: `Breaking changes`, `Implemented enhancements`, `Fixed bugs`, and `Merged pull requests`. Any unlabeled PRs will be found in `Merged pull requests`. It's important to make sure that any `breaking changes`, `enhancements`, or `bug fixes` are pulled up out of `merged pull requests` into the correct category. Housekeeping, tech debt clearing, infra changes, or refactoring do not count as `enhancements`. Only enhancements a user benefits from should be listed in that category. - - Make sure that the "Full Changelog" link is actually comparing the correct tags (normally your released version against the previously version). - - Make sure that release notes and breaking changes are present. diff --git a/docs/contributing/release-process.md b/docs/contributing/release-process.md index d00e9d43987..a4ad7804716 100644 --- a/docs/contributing/release-process.md +++ b/docs/contributing/release-process.md @@ -1,14 +1,62 @@ -# Release Process +# Releasing Feast -Feast uses [semantic versioning](https://semver.org/). +## Versioning policy and branch workflow + +Feast uses [semantic versioning](https://semver.org/). As such, while it is still pre-1.0 breaking changes will happen in minor versions. + +Contributors are encouraged to understand our branch workflow described below, for choosing where to branch when making a change (and thus the merge base for a pull request). * Major and minor releases are cut from the `master` branch. -* Whenever a major or minor release is cut, a branch is created for that release. This is called a "release branch". For example if `0.3` is released from `master`, a branch named `v0.3-branch` is created. -* You can create a release branch via the GitHub UI. -* From this branch a git tag is created for the specific release, for example `v0.3.0`. -* Tagging a release will automatically build and push the relevant artifacts to their repositories or package managers \(docker images, Python wheels, etc\). -* A release branch should be substantially _feature complete_ with respect to the intended release. Code that is committed to `master` may be merged or cherry-picked on to a release branch, but code that is directly committed to the release branch should be solely applicable to that release \(and should not be committed back to master\). -* In general, unless you're committing code that only applies to the release stream \(for example, temporary hotfixes, backported security fixes, or image hashes\), you should commit to `master` and then merge or cherry-pick to the release branch. -* It is also important to update the [CHANGELOG.md](https://github.com/gojek/feast/blob/master/CHANGELOG.md) when submitting a new release. This can be in the same PR or a separate PR. -* Finally it is also important to create a [GitHub release](https://github.com/gojek/feast/releases) which includes a summary of important changes as well as any artifacts associated with that release. +* Each major and minor release has a long-lived maintenance branch, for example `v0.3-branch`. This is called a "release branch". +* From the release branches, patch version releases are tagged, for example `v0.3.0`. + +A release branch should be substantially _feature complete_ with respect to the intended release. Code that is committed to `master` may be merged or cherry-picked on to a release branch, but code that is directly committed to a release branch should be solely applicable to that release \(and should not be committed back to master\). + +In general, unless you're committing code that only applies to a particular release stream \(for example, temporary hotfixes, backported security fixes, or image hashes\), you should base changes from `master` and then merge or cherry-pick to the release branch. + +## Release process + +For Feast maintainers, these are the concrete steps for making a new release. + +1. For a major or minor release, create and check out the release branch for the new stream, e.g. `v0.6-branch`. For a patch version, check out the stream's release branch. +1. Update the [CHANGELOG.md]. See the [Creating a change log](#creating-a-change-log) guide. +1. In the root `pom.xml`, remove `-SNAPSHOT` from the `` property, and commit. +1. Push. For a new release branch, open a PR against master. +1. When CI passes, merge. (Remember _not_ to delete the new release branch). +1. Tag the merge commit with the release version, using a `v` prefix. Push the tag. +1. Bump to the next working version and append `-SNAPSHOT` in `pom.xml`. +1. Commit the POM and open a PR. +1. Create a [GitHub release](https://github.com/gojek/feast/releases) which includes a summary of important changes as well as any artifacts associated with the release. Make sure to include the same change log as added in [CHANGELOG.md]. Use `Feast vX.Y.Z` as the title. +1. Create one final PR to the master branch and also update its [CHANGELOG.md]. + +When a tag that matches a Semantic Version string is pushed, CI will automatically build and push the relevant artifacts to their repositories or package managers \(docker images, Python wheels, etc\). JVM artifacts are promoted from Sonatype OSSRH to Maven Central, but it sometimes takes some time for them to be available. + +[CHANGELOG.md]: https://github.com/gojek/feast/blob/master/CHANGELOG.md + +### Creating a change log +We use an [open source change log generator](https://hub.docker.com/r/ferrarimarco/github-changelog-generator/) to generate change logs. The process still requires a little bit of manual effort. +1. Create a GitHub token as [per these instructions ](https://github.com/github-changelog-generator/github-changelog-generator#github-token). The token is used as an input argument (`-t`) to the changelog generator. +2. The change log generator configuration below will look for unreleased changes on a specific branch. The branch will be `master` for a major/minor release, or a release branch (`v0.4-branch`) for a patch release. You will need to set the branch using the `--release-branch` argument. +3. You should also set the `--future-release` argument. This is the version you are releasing. The version can still be changed at a later date. +4. Update the arguments below and run the command to generate the change log to the console. +``` +docker run -it --rm ferrarimarco/github-changelog-generator \ +--user gojek \ +--project feast \ +--release-branch \ +--future-release \ +--unreleased-only \ +--no-issues \ +--bug-labels kind/bug \ +--enhancement-labels kind/feature \ +--breaking-labels compat/breaking \ +-t \ +--max-issues 1 \ +-o +``` +5. Review each change log item. + - Make sure that sentences are grammatically correct and well formatted (although we will try to enforce this at the PR review stage). + - Make sure that each item is categorized correctly. You will see the following categories: `Breaking changes`, `Implemented enhancements`, `Fixed bugs`, and `Merged pull requests`. Any unlabeled PRs will be found in `Merged pull requests`. It's important to make sure that any `breaking changes`, `enhancements`, or `bug fixes` are pulled up out of `merged pull requests` into the correct category. Housekeeping, tech debt clearing, infra changes, or refactoring do not count as `enhancements`. Only enhancements a user benefits from should be listed in that category. + - Make sure that the "Full Changelog" link is actually comparing the correct tags (normally your released version against the previously version). + - Make sure that release notes and breaking changes are present.