Document release process of edgedb-server

dev-notes/release-process.md

@@ -0,0 +1,158 @@
+# Instructions for releasing a new version
+
+EdgeDB packages are published on https://packages.edgedb.com.
+They are build in GitHub Actions pipelines, using
+https://github.com/edgedb/edgedb-pkg.
+
+Releases are built from a release branch associated with a major version
+(i.e. "release/4.x"). At feature freeze, we create this branch. From that moment
+on, all additional commits will have to be cherry-picked to this branch.
+
+Before the major version, we publish "testing releases":
+
+- "alpha" (i.e. `v4.0a1`, `v4.0a2`),
+- "beta" (i.e. `v4.0b1`, `v4.0b2`),
+- "release candidates" (`v4.0rc1`) that we might promote into the final release.
+
+## Preparing commits for a release
+
+We have GitHub labels (i.e. "backport-4.x") associated with each major release
+that indicate PRs that should be backported to the release branch.
+
+It should be sufficient to go over that list and cherry-pick PR commits to the
+release branch.
+
+Sometimes, people will forget to tag the PR to be back-ported, so a good
+practice is to list all commits since the last release:
+
+```
+git show releases/4.x # to see the last commit that has been cherry-picked
+git log master # find the hash of that commit on master
+git log hash_of_that_commit..master > ../to-backport.txt
+```
+
+Now, one can go trough the list and see if the commits are worth back-porting.
+A few pointers:
+
+- Don't backport docs, since the website is built from master.
+- Don't backport refactors, since they might introduce bugs and there is no
+  point in improving the codebase of a branch we are not developing on anymore.
+  Disregard this rule early on after the fork of the release branch, since
+  porting refactors will decrease chances merge conflicts of other commits later
+  on.
+- Don't backport "build" commits (updating of build deps, refactoring of the
+  release pipeline), since that might trigger problems in the release process.
+- If a PR changes any of the schema objects (i.e. adding a field to
+  `s_types.Type`) or metaschema (i.e. changing a pg function
+  `edgedb.range_to_jsonb`), a "patch" needs to be added into `pgsql/patches.py`.
+  This is needed, because minor releases don't require a "dump and restore", so
+  we must apply these changes to existing user databases.
+
+A helper shell script to cherry-pick a commit using it's PR number:
+
+```bash
+# this won't work if a PR is not squashed into a single commit
+function cp-pr {
+    git cherry-pick $(gh pr view $1 --json mergeCommit --jq .mergeCommit.oid)
+}
+```
+
+## Release pipeline
+
+When you have your commits ready, tag the commit and push:
+
+```
+# git tag --sign v4.5
+# git push origin releases/4.x --follow-tags
+```
+
+Then open GitHub Actions page and run one of these pipelines:
+
+- https://github.com/edgedb/edgedb/actions/workflows/testing.yml
+- https://github.com/edgedb/edgedb/actions/workflows/release.yml
+
+This will kick-off an GHA workflow that should take ~3 hours.
+It will build, test and publish for each of the supported platforms.
+It will not publish any packages if any of the tests fail.
+
+Sometimes, tests will be flakey and just need to be re-run.
+You can do that with a button top-right.
+
+## Changelog
+
+Each major release has a changelog page in the docs (i.e.
+`docs/changelog/4_x.rst`). It should contain explanations of the new features,
+which are usually composed by our dev-rel team.
+
+Each minor release is just a subsection in the page, as a list of back-ported
+PRs. Any PRs that fix internal stuff (like our test framework) or are not user
+facing should not be included in the changelog.
+
+These changes need to land on master branch and are not needed on the release
+branch, so best course of action if to open a PR to master after kicking off
+the release pipeline. After that PR is merged, the website needs to be
+deployed, for changelog to land on the website (ping dev rel team).
+
+A helper script to generate changelog:
+
+```python
+# I keep this in ../compose-changelog.py
+
+import json
+import requests
+import re
+import sys
+
+BASE_URL = 'https://api.github.com/repos/edgedb/edgedb/compare'
+
+def main():
+    if len(sys.argv) < 2:
+        print('pass a sha1 hash as a first argument')
+        sys.exit(1)
+
+    from_hash = sys.argv[1]
+    if len(sys.argv) > 2:
+        to_hash = sys.argv[2]
+
+    r = requests.get(f'{BASE_URL}/{from_hash}...{to_hash}')
+    data = json.loads(r.text)
+
+    for commit in data['commits']:
+        message = commit['commit']['message']
+        first_line = message.partition('\n\n')[0]
+        if commit.get('author'):
+            username = '@{}'.format(commit['author']['login'])
+        else:
+            username = commit['commit']['author']['name']
+        sha = commit["sha"][:8]
+
+        m = re.search(r'\#(?P<num>\d+)\b', message)
+        if m:
+            issue_num = m.group('num')
+        else:
+            issue_num = None
+
+        first_line = re.sub(r'\(\#(?P<num>\d+)\)', '', first_line)
+        print(f'* {first_line}')
+        # print(f'  (by {username} in {sha}', end='')
+        if issue_num:
+            print(f'  (:eql:gh:`#{issue_num}`)')
+        print()
+
+if __name__ == '__main__':
+    main()
+```
+
+```bash
+python ../compose-changelog.py v4.5 v4.6 >> docs/changelog/4_x.rst
+```
+
+## After the release
+
+The release pipelines will make the new version available at
+https://packages.edgedb.com. This is enough for it to be installable using the
+CLI, but other methods of installation need to be kicked of manually:
+
+- our cloud team needs to deploy separate _cloud wizardly groups_,
+- docker image needs to be published to https://hub.docker.com,
+- Digital Ocean image needs to be published by Frederick,