Document release steps #476

ches · 2020-02-13T23:55:43Z

What this PR does / why we need it:

Attempts to document release procedure, and separate what concerns contributors (versioning policy and branch workflow) versus what concerns maintainers.

This doc is in GitBook but these changes need discussion: the procedure is my guess, I haven't done it so I'll need your help to correct errors and omissions.

A couple of remarks or observations with what I have here:

I'm not sure that the conventional Maven SNAPSHOT dance has been practiced consistently to this point. We could discuss alternatives, but so long as we intend to use it, tagged release commits ideally ought to not contain -SNAPSHOT in the POM. I've suggested a procedure that maintains this, but it's unfortunately a lot of ceremony when you have branch protection, the snapshot dance, and changelog update (2 PRs, several redundant CI builds). Some ceremony is warranted for major releases I think, but it'd be nice if it could be one PR somehow.

One redundant build is inevitable with the snapshot convention I think, even if branch protection was skipped: CI passed on latest master, but a commit is needed to remove -SNAPSHOT before tagging.
A shortcoming with the changelog generator seems to be that, as far as I understand, the released version needs to be tagged (and pushed to GitHub?) before you run it. Ideally IMO changelog would precede the tagged commit, even makes a good candidate to be the tagged release commit along with version string updates.

Having a changelog to scan is helpful before making a version number decision, to review the Semantic Versioning implications of the release. You could run the tool in dry-run stdout mode for that I guess, but if you wanted to commit it before the act of tagging, you'll be left manually editing the file with the intended version number.

Which issue(s) this PR fixes:

Relates to #442, subsequent private conversation about whether others with certain maintainer rights are able to make releases.

Does this PR introduce a user-facing change?:

NONE

khorshuheng · 2020-02-14T02:11:21Z

/test test-end-to-end-batch

ches · 2020-02-14T04:09:39Z

docs/contributing.md

+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 `<revision>` property, and commit.


Are there any other places that version strings need to be updated?

Too many unfortunately. Let me see if I can source these. As long as we have the complete list we can always try to reduce it over time.

I noticed version for Helm charts on #477

Wow, it's not actually looking too bad. These are the ones I found.

pom.xml

infra/charts/feast/requirements.yaml

infra/charts/feast/Chart.yaml

infra/charts/feast/values.yaml

infra/charts/feast/charts/feast-core/Chart.yaml

infra/charts/feast/charts/feast-serving/Chart.yaml

ches · 2020-02-14T04:40:01Z

docs/contributing.md

+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


Perhaps we can set options to map Feast's label conventions to the generator's grouping ones, like --enhancement-labels kind/feature --bug-labels kind/bug

That would be super cool.

I am just a bit worried that we havent been tagging everything diligently yet. Perhaps we should add this a bit later.

woop · 2020-02-14T06:11:32Z

@ches I need to merge some changes into this same markdown doc, although its more structural. You will probably have to refactor your PR slightly, but it shouldnt be too hard.

ches · 2020-02-14T06:42:31Z

I need to merge some changes into this same markdown doc, although its more structural. You will probably have to refactor your PR slightly, but it shouldnt be too hard.

No worries, let me know when it's in. If you're not already doing something similar, as per #420 (comment) I was going to basically pull out everything above the "Development" header to a new Getting Started or Quick Start page, then tweak Contributing with some new introduction.

Those are probably fairly uncontroversial changes / can be iterated on without discussion through GitBook, unlike the release procedure.

woop · 2020-02-14T07:25:12Z

I need to merge some changes into this same markdown doc, although its more structural. You will probably have to refactor your PR slightly, but it shouldnt be too hard.

No worries, let me know when it's in. If you're not already doing something similar, as per #420 (comment) I was going to basically pull out everything above the "Development" header to a new Getting Started or Quick Start page, then tweak Contributing with some new introduction.

Those are probably fairly uncontroversial changes / can be iterated on without discussion through GitBook, unlike the release procedure.

I submitted my changes. Gitbook also has "dropdown" menu items now, so we can organize all of this information under a nice heading if you think that makes sense.

Feel free to make edits as necessary.

woop · 2020-02-14T07:47:43Z

What this PR does / why we need it:

Attempts to document release procedure, and separate what concerns contributors (versioning policy and branch workflow) versus what concerns maintainers.

This doc is in GitBook but these changes need discussion: the procedure is my guess, I haven't done it so I'll need your help to correct errors and omissions.

A couple of remarks or observations with what I have here:

I'm not sure that the conventional Maven SNAPSHOT dance has been practiced consistently to this point. We could discuss alternatives, but so long as we intend to use it, tagged release commits ideally ought to not contain -SNAPSHOT in the POM. I've suggested a procedure that maintains this, but it's unfortunately a lot of ceremony when you have branch protection, the snapshot dance, and changelog update (2 PRs, several redundant CI builds). Some ceremony is warranted for major releases I think, but it'd be nice if it could be one PR somehow.

The release automation right now is a little bit manual still. Do you have examples of how this can be rolled into a single PR? Perhaps just making sure everyone agrees to and follows a process is a start, which is why I like this PR. Ideally this would be automated away from people, but I think we have lower hanging fruit right now.

One redundant build is inevitable with the snapshot convention I think, even if branch protection was skipped: CI passed on latest master, but a commit is needed to remove -SNAPSHOT before tagging.

A shortcoming with the changelog generator seems to be that, as far as I understand, the released version needs to be tagged (and pushed to GitHub?) before you run it. Ideally IMO changelog would precede the tagged commit, even makes a good candidate to be the tagged release commit along with version string updates.

Yes, having it be the tagged commit makes sense to me as well.

stale · 2020-04-14T08:55:51Z

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

ches · 2020-04-21T06:08:02Z

Quoting @woop from #442 because I think it's more contextual here:

I'm trying to figure out what all the missing pieces are here. @ches is it possible for you to enumerate your uncertainties? Or if you have certainties (like access you need) then you could also let me know and I will try to address them.

I think what I'd like to suggest at this point is for someone who has actually released Feast before to follow this PR's guide to make a release for v0.3.6 / 0.3.7, fill in anything missing in my doc as you go, and send a PR against this one that fills in the gaps. Basically, I don't know what I don't know 😊

Before we postulate how process/automation could potentially be improved, let's first accurately capture how it actually works at present. Hopefully that breaks the impasse.

woop · 2020-04-23T16:43:57Z

I don't know what I don't know

Touché.

follow this PR's guide to make a release for v0.3.6 / 0.3.7, fill in anything missing in my doc as you go

Sure, makes sense. We are also in a bit of crunch mode right now, so I do apologize for the lack of attention here. I've not gone through the complete cycle myself so I will defer to @davidheryanto and @khorshuheng here.

woop · 2020-04-30T01:48:18Z

A shortcoming with the changelog generator seems to be that, as far as I understand, the released version needs to be tagged (and pushed to GitHub?) before you run it.

It seems like the changelog generator has an unreleased section that it generates. If we are assuming that all unreleased changes would make it into the release, then I think it solves the problem.

For example I just ran it

Changelog

Unreleased

Full Changelog

Closed issues:

Feast Core: Dataflow Runner fails to start job with no translator registered error. #642
Feast Serving not registering store in Feast Core #640
[SNIP]

Merged pull requests:

Fix config validation for feast.jobs.metrics.host #662 (davidheryanto)
Docker compose bug fix #661 (woop)
Upgrade github checkout action to v2 #660 (khorshuheng)

Even makes a good candidate to be the tagged release commit along with version string updates.

If the above holds true, then we could use the changelog generator to create the changelog. Push it with the version string updates. Review it. Get it merged. Push the tag.

But the problem is we still need the pom.xml / Snapshot addition after that, right? I don't see a way around having two PRs, unless we just want to push straight to master to add that back in.

Overall I think the process you have described makes sense. Changes/additions

Update the order of events to include the changelog in the release commit
Add more details on how to generate the changelog. I think this can be a different section altogether. You can just link to the header.
Add more details on how to document the GitHub release summary page.

I can help with (2) and (3)

Once we have updated the above, somebody should then walk through it.

woop · 2020-04-30T05:25:34Z

Generating a Change Log

We use an open source change log generator to generate change logs. The process still requires a little bit of manual effort.

Create a GitHub token as per these instructions . The token is used as an input argument (-t) to the changelog generator.
The change log generator 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.
It is also advised to set a proposed version. This is the version that you will be releasing. The version can still be changed at a later date. Please use --future-release to set this version using semver format.
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 <release-branch-to-find-changes>  \
--future-release <proposed-release-version>  \
--unreleased-only  \
--no-issues  \
--bug-labels kind/bug  \
--enhancement-labels kind/feature  \
--breaking-labels compat/breaking  \
-t <your-github-token>  \
--max-issues 1 \
-o

Please 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.

Example (unmodified)

docker run -it --rm ferrarimarco/github-changelog-generator \
--user gojek \
--project feast  \
--future-release 0.5.0  \
--unreleased-only  \
--no-issues  \
--bug-labels kind/bug  \
--enhancement-labels kind/feature  \
--release-branch master  \
--breaking-labels compat/breaking  \
-t <your-github-token>  \
--max-issues 1 -o

Changelog

0.5.0 (2020-04-30)

Full Changelog

Breaking changes:

Clean up Feast configuration #611 (woop)

Implemented enhancements:

Add Ingestion Job management API for Feast Core #548 (mrzzy)

Fixed bugs:

Fix config validation for feast.jobs.metrics.host #662 (davidheryanto)
Docker compose bug fix #661 (woop)
Swap join columns #647 (zhilingc)
Fix Feast Serving not registering its store in Feast Core #641 (mrzzy)

Merged pull requests:

Add label checking to Prow #665 (woop)
Upgrade github checkout action to v2 #660 (khorshuheng)
Fix redis cluster e2e #659 (terryyylim)
core: Use Runner enum type instead of string for Job model #651 (ches)
JobUpdateTask cleanups #650 (ches)
...

woop · 2020-05-01T08:53:38Z

One open question: Which changelog do we update? Clearly we want to update the master branch, but is it sufficient to only update master and the respective release branch? If we have to update master then we would be updating the change log in three places, and we need 3 PRs.

woop · 2020-05-02T01:56:09Z

I've updated the guide. You might want to have a quick look. It works fine for the most part. I think we should perhaps resolve conflicts and merge this in, and then add more details on which artifacts are being produced. That might be a separate section though.

ches · 2020-05-04T08:33:10Z

Thanks for the updates! LGTM, I will fix the conflicts shortly.

Separate what concerns contributors versus what concerns maintainers.

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.

ches · 2020-05-05T01:57:51Z

Rebased, and moved this to the broken out release-process.md that exists now. Master still has the monolithic contributing/contributing.md where this patch still applied and broken out pages with the same information (some of which missed good updates to the monolith I think).

That'll get sorted out, but now it's easier to port to the v0.4-branch docs that are live on GitBook. I can send a PR for that as well.

woop · 2020-05-05T02:25:49Z

Thanks @ches. I can help with cleanup. For the time being I'd just like to get this merged in. We won't lose it, I promise :)

woop · 2020-05-08T02:10:32Z

/lgtm

woop · 2020-05-08T02:17:57Z

/approved

khorshuheng · 2020-05-08T02:24:38Z

/approve

feast-ci-bot · 2020-05-08T02:24:43Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: ches, khorshuheng, woop

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

~~OWNERS~~ [khorshuheng,woop]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

ches added do-not-merge/work-in-progress area/documentation labels Feb 13, 2020

ches requested review from davidheryanto, khorshuheng, pradithya, woop and zhilingc as code owners February 13, 2020 23:55

feast-ci-bot added the size/M label Feb 13, 2020

ches commented Feb 14, 2020

View reviewed changes

This was referenced Mar 27, 2020

[chore] Make v0.3.7 release, publish artifacts for v0.3.6 also #442

Closed

Fix version on master branch #589

Closed

stale bot added the wontfix This will not be worked on label Apr 14, 2020

woop added the keep-open label Apr 15, 2020

stale bot removed the wontfix This will not be worked on label Apr 15, 2020

woop mentioned this pull request Apr 30, 2020

Add label checking to Prow #665

Merged

woop mentioned this pull request May 1, 2020

Release v0.3.7 #670

Merged

ches and others added 3 commits May 5, 2020 08:26

Document release steps

045e95d

Separate what concerns contributors versus what concerns maintainers.

Update release process with changelog guide

b3aa35e

ches removed the do-not-merge/work-in-progress label May 5, 2020

ches changed the title ~~[WIP] Document release steps~~ Document release steps May 5, 2020

feast-ci-bot assigned woop May 8, 2020

feast-ci-bot added the lgtm label May 8, 2020

woop approved these changes May 8, 2020

View reviewed changes

feast-ci-bot added the approved label May 8, 2020

woop merged commit 90edb71 into feast-dev:master May 8, 2020

ches deleted the release-doc branch May 8, 2020 03:30

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document release steps #476

Document release steps #476

ches commented Feb 13, 2020

khorshuheng commented Feb 14, 2020

ches Feb 14, 2020

woop Feb 14, 2020

ches Feb 14, 2020

woop Feb 14, 2020

ches Feb 14, 2020

woop Feb 14, 2020

woop commented Feb 14, 2020

ches commented Feb 14, 2020 •

edited

Loading

woop commented Feb 14, 2020

woop commented Feb 14, 2020

stale bot commented Apr 14, 2020

ches commented Apr 21, 2020

woop commented Apr 23, 2020 •

edited

Loading

woop commented Apr 30, 2020 •

edited

Loading

woop commented Apr 30, 2020 •

edited

Loading

woop commented May 1, 2020

woop commented May 2, 2020

ches commented May 4, 2020

ches commented May 5, 2020

woop commented May 5, 2020

woop commented May 8, 2020

woop commented May 8, 2020

khorshuheng commented May 8, 2020

feast-ci-bot commented May 8, 2020

Document release steps #476

Document release steps #476

Conversation

ches commented Feb 13, 2020

khorshuheng commented Feb 14, 2020

ches Feb 14, 2020

Choose a reason for hiding this comment

woop Feb 14, 2020

Choose a reason for hiding this comment

ches Feb 14, 2020

Choose a reason for hiding this comment

woop Feb 14, 2020

Choose a reason for hiding this comment

ches Feb 14, 2020

Choose a reason for hiding this comment

woop Feb 14, 2020

Choose a reason for hiding this comment

woop commented Feb 14, 2020

ches commented Feb 14, 2020 • edited Loading

woop commented Feb 14, 2020

woop commented Feb 14, 2020

stale bot commented Apr 14, 2020

ches commented Apr 21, 2020

woop commented Apr 23, 2020 • edited Loading

woop commented Apr 30, 2020 • edited Loading

Changelog

Unreleased

woop commented Apr 30, 2020 • edited Loading

Generating a Change Log

Example (unmodified)

Changelog

0.5.0 (2020-04-30)

woop commented May 1, 2020

woop commented May 2, 2020

ches commented May 4, 2020

ches commented May 5, 2020

woop commented May 5, 2020

woop commented May 8, 2020

woop commented May 8, 2020

khorshuheng commented May 8, 2020

feast-ci-bot commented May 8, 2020

ches commented Feb 14, 2020 •

edited

Loading

woop commented Apr 23, 2020 •

edited

Loading

woop commented Apr 30, 2020 •

edited

Loading

woop commented Apr 30, 2020 •

edited

Loading