Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation of release process #239

Merged
merged 2 commits into from
Mar 13, 2024
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 54 additions & 0 deletions RELEASE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
# Releasing connect-kotlin

Connect-Kotlin’s repository has a release workflow which publishes connect-kotlin
artifacts to public maven. The release process was intentionally designed to be
as friction-free as possible — the result is that you just create/tag a release
in GitHub, and everything else is automated after that.

Using the Github UI, create a new release like so:
* Under “Choose a tag”, type in “vX.Y.Z” to create a new tag for the release upon publish.
Note: The release job does infer the version from the release string and expects versions
to start with `v` (e.g. `v0.1.0`).
* Target the main branch.
* Title the Release the same as the tag: “vX.Y.Z”.
* Click “set as latest release”.
* Set the last version as the “Previous tag”.
* Click “Generate release notes” to autogenerate release notes.
* Edit the release notes.
* Tweak the change description for each if necessary so it summarizes the salient
aspect(s) of the change in a single sentence. Detail is not needed as a user could
follow the link to the relevant PR. (Potentially take a pass at PR descriptions
and revise to increase clarity for users that visit the PRs from the release notes.)
* Related commits can be grouped together with a single entry that has links to all
relevant PRs (and attributes all relevant contributors).
* A summary may be added if warranted.
* The items in the list should be broken up into sub-categories. The typical
sub-categories to use follow:
* **API Improvements**: If the API was changed in any backwards-incompatible ways
to improve developer experience, mention those here. Details on breaking changes
should accompany the change log with a separate section titled "API Updates".
(This category should go away once we reach a stable API and a v1.0.)
* **Enhancements**: New features or additions/improvements to existing features.
* **Bugfixes**: Self-explanatory -- fixes to defects.
* **Other Changes**: Other noteworthy changes in the codebase or tests. In some
way these could be considered enhancements, but they are more for maintenance
and aid future contributors vs. providing new features to users. Use your
best judgement when deciding if something warrants appearing here. Things like
dependency updates and the like do _not_ warrant appearing here and should be
removed from the auto-generated release notes.
* If there were API changes that are not backwards compatible, add an "API Updates"
section that enumerates the changes via a bullet list per class/type that was
incompatibly changed.
* An example of past release notes that contain many of these sections can be
reviewed here: https://github.com/connectrpc/connect-kotlin/releases/tag/v0.5.0
* Click "Save Draft" and then share the link to have the notes reviewed by at least one
other [maintainer](https://github.com/connectrpc/connect-kotlin/blob/main/MAINTAINERS.md).
* After the notes are approved (after some potential iteration and revision), you can
finally create the release by clicking "Publish Release".

After the GitHub release has been created, you can verify that the rest of the process
completes successfully by following the corresponding run of the "release" GitHub
workflow: https://github.com/connectrpc/connect-kotlin/actions/workflows/release.yml

Once the workflow is complete, the release is complete and artifacts have been
successfully published to Maven Central.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should probably indicate they'll show up at https://repo1.maven.org/maven2/com/connectrpc/ after a delay - Maven publishes first to https://s01.oss.sonatype.org/content/repositories/releases/com/connectrpc/.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is that latter URL stable enough to also include in this doc?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added a couple of sentences. Let me know if they are accurate.

Loading