Skip to content

Revise release instructions #1384

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.

Sign up for GitHub

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

Merged
merged 7 commits into from
Nov 23, 2022
Merged

Revise release instructions #1384

Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
0deeb53
Revise release instructions
jmikola Nov 23, 2022
e81b08b
Use more diff code blocks for concise example
jmikola Nov 23, 2022
6b4db17
Apply suggestions from code review
jmikola Nov 23, 2022
d593ee8
Revise release notes example
jmikola Nov 23, 2022
b0b9435
Apply syntax highlighting to release notes example
jmikola Nov 23, 2022
46bd3c8
Re-order release steps
jmikola Nov 23, 2022
6653f24
Fix diff indentation
jmikola Nov 23, 2022
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
153 changes: 93 additions & 60 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -281,8 +281,18 @@ generation script.

## Releasing

The follow steps outline the release process for a maintenance branch (e.g.
releasing the `vX.Y` branch as X.Y.Z).
The following steps outline the release process for both new minor versions (e.g.
releasing the `master` branch as X.Y.0) and patch versions (e.g. releasing the
`vX.Y` branch as X.Y.Z).

The command examples below assume that the canonical "mongodb" repository has
the remote name "mongodb". You may need to adjust these commands if you've given
the remote another name (e.g. "upstream"). The "origin" remote name was not used
as it likely refers to your personal fork.
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 imagine most development environments are clones of a personal fork, so it's unlikely that "origin" (the default) would be correct. In any event, specifying a remote name in the examples adds clarity.


It helps to keep your own fork in sync with the "mongodb" repository (i.e. any
branches and tags on the main repository should also exist in your fork). This
is left as an exercise to the reader.
Copy link
Member Author

Choose a reason for hiding this comment

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

@alcaeus: I dunno if I've shared this with you, but this is what I use locally:

#!/bin/sh

current=$(git rev-parse --abbrev-ref HEAD)

git fetch mongodb
git fetch origin

for branch in master v1.14 v1.15; do
  git checkout $branch && git pull mongodb $branch && git push origin $branch
done

git checkout $current

Dunno if you think it's worth documenting elsewhere.


### Transition JIRA issues and version

Expand Down Expand Up @@ -312,18 +322,13 @@ Update the version and stability constants in `phongo_version.h`. This should
entail removing the version's "-dev" suffix, changing the stability to
"stable", and increasing the last digit for `PHP_MONGO_VERSION_DESC`:

```
#define PHP_MONGODB_VERSION "1.1.8-dev"
#define PHP_MONGODB_STABILITY "devel"
#define PHP_MONGODB_VERSION_DESC 1,1,8,0
```

The above would be changed to:

```
#define PHP_MONGODB_VERSION "1.1.8"
#define PHP_MONGODB_STABILITY "stable"
#define PHP_MONGODB_VERSION_DESC 1,1,8,1
```diff
-#define PHP_MONGODB_VERSION "1.1.8-dev"
-#define PHP_MONGODB_STABILITY "devel"
-#define PHP_MONGODB_VERSION_DESC 1,1,8,0
+#define PHP_MONGODB_VERSION "1.1.8"
+#define PHP_MONGODB_STABILITY "stable"
+#define PHP_MONGODB_VERSION_DESC 1,1,8,1
Copy link
Member

Choose a reason for hiding this comment

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

It may be worth mentioning that for going from x.y.z-dev to x.y.z the last digit in this number needs to be increased by 1, not reset to 0. I've been confused by this before, especially during my first releases.

Copy link
Member Author

Choose a reason for hiding this comment

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

Isn't that stated in the preceding paragraph?

This should entail removing the version's "-dev" suffix, changing the stability to "stable", and increasing the last digit for PHP_MONGO_VERSION_DESC:

Copy link
Member

Choose a reason for hiding this comment

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

I may need new glasses. Thanks for pointing this out!

```

The Makefile targets for creating the PECL package depend on these constants, so
Expand Down Expand Up @@ -352,46 +357,70 @@ After copying release notes, use `make package` to create the package file (e.g.
$ pecl install -f mongodb-X.Y.Z.tgz
```

### Commit version update and release notes
### Update version info

Commit the modified `phongo_version.h` file as "Package X.Y.Z"
Commit the modified `phongo_version.h` file and push this change:

```
$ git add phongo_version.h
$ git commit -m "Package X.Y.Z"
$ git push mongodb
```

### Tag release
> **Note:** Pushing this commit independently from the subsequent "Back to -dev"
> commit will ensure that Windows build artifacts are created for the release.
Copy link
Member Author

Choose a reason for hiding this comment

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

GitHub Actions are smart enough to not build individual commits if multiple are pushed at once. The original example we had where "Package X.Y.Z" and "Back to -dev" were pushed simultaneously would have meant we never generate build artifacts for the actual tag.

This is clunky and definitely something we could improve down the line if we stop depending on build artifacts from a previous CI run and instead build DLLs on-demand for releases. We could also avoid debug builds and PDB file generation for typical CI runs (I imagine that's a bit slower than without).

Copy link
Member

Choose a reason for hiding this comment

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

There is the option of pushing them at the same time, then pushing the tag separately and ensuring the tag is built. The workflow syntax allows you to specify tag filters to build on a push: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#example-including-branches-and-tags.

If we're updating the process down the line, we could change the process to build tags and create a draft release for them, attaching build artifacts in the process. We could then revise the release notes separately. For now I don't think we need to change this, as I'm sure we'll be working on automating releases (including PECL packages) in the near future.

Copy link
Member Author

Choose a reason for hiding this comment

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

Noted. I didn't consider that since we currently only have branch filters in place.

If we revisit release automation down the line I'd definitely suggest writing up a design doc first so we can plan out exactly what we want to implement.

Copy link
Member

Choose a reason for hiding this comment

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

I agree, that change exceeds the scope of getting this to work. I suggest putting release automation on our quarterly plan and designing this ahead of time 👍


### Ensure Windows build artifacts exist

Windows builds are tested by GitHub Actions. Each successful build for a pushed
commit will produce a build artifact consisting of DLL and PDB files for that
environment (e.g. 8.0-nts-x64). These build artifacts are later used to create
release assets (see:
[windows-release-build.yml](.github/workflows/windows-release-build.yml)).

Before publishing a release in GitHub, ensure that all Windows builds for the
tag's commit have succeeded and that the necessary build artifacts have been
created. This can be done by examining the build artifacts in the workflow run
summary for the "Package X.Y.Z" commit (i.e. tag target).

> **Note:** the "published" event applies to both releases and pre-releases. See
> [Events that trigger workflows: release](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#release)
> for more details.

### Tag the release

The previous commit will be the target for our release tag:
Create a tag for the release and push:

```
$ git tag -a -m "Release X.Y.Z" X.Y.Z
$ git push mongodb --tags
```

### Update version info back to dev
### Release PECL package

After tagging, the version and stability constants in `phongo_version.h` should be
updated back to development status.
The PECL package may be published via the
[Release Upload](https://pecl.php.net/release-upload.php) form. You will have
one chance to confirm the package information after uploading.

```
#define PHP_MONGODB_VERSION "1.1.8"
#define PHP_MONGODB_STABILITY "stable"
#define PHP_MONGODB_VERSION_DESC 1,1,8,1
```
### Update version info back to dev

The above would be changed to:
After tagging, the version and stability constants in `phongo_version.h` should
be updated back to development status.

```
#define PHP_MONGODB_VERSION "1.1.9-dev"
#define PHP_MONGODB_STABILITY "devel"
#define PHP_MONGODB_VERSION_DESC 1,1,9,0
```diff
-#define PHP_MONGODB_VERSION "1.1.8"
-#define PHP_MONGODB_STABILITY "stable"
-#define PHP_MONGODB_VERSION_DESC 1,1,8,1
+#define PHP_MONGODB_VERSION "1.1.9-dev"
+#define PHP_MONGODB_STABILITY "devel"
+#define PHP_MONGODB_VERSION_DESC 1,1,9,0
```

Commit this change:
Commit and push this change:

```
$ git commit -m "Back to -dev" phongo_version.h
$ git push mongodb
```

> **Note:** If this is an alpha, beta, or RC release, the version string should
Expand All @@ -400,65 +429,69 @@ $ git commit -m "Back to -dev" phongo_version.h
> "1.4.0beta1" and "beta" for the first beta release, this step would see them
> ultimately changed to "1.4.0beta2-dev" and "devel".

### Push commits and tags
### Branch management

#### After releasing a new minor version

After a new minor version is released (i.e. `master` was tagged), a maintenance
branch should be created for future patch releases:

```
$ git push
$ git push --tags
$ git checkout -b vX.Y
$ git push mongodb vX.Y
```

### Ensure Windows build artifacts exist
Update `phongo_version.h` for the `master` branch:

Windows builds are tested by GitHub Actions. Each successful build for a pushed
commit will produce a build artifact consisting of DLL and PDB files for that
environment (e.g. 8.0-nts-x64). These build artifacts are later used to create
release assets (see:
[windows-release-build.yml])(.github/workflows/windows-release-build.yml).
Before publishing a release in GitHub, ensure that all Windows builds for the
tag's commit have succeeded and that the necessary build artifacts have been
created.
```diff
-#define PHP_MONGODB_VERSION "1.15.1-dev"
+#define PHP_MONGODB_VERSION "1.16.0-dev"
#define PHP_MONGODB_STABILITY "devel"
-#define PHP_MONGODB_VERSION_DESC 1,15,1,0
+#define PHP_MONGODB_VERSION_DESC 1,16,0,0
```

Note: the "published" event applies to both releases and pre-releases. See
[Events that trigger workflows: release](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#release)
for more details.
Commit and push this change:

### Release PECL package
```
$ git commit -m "Master is now X.Y-dev" phongo_version.h
$ git push mongodb
```

The PECL package may be published via the
[Release Upload](https://pecl.php.net/release-upload.php) form. You will have
one chance to confirm the package information after uploading.
#### After releasing a patch version

### Merge the maintenance branch up to master
If this was a patch release, the maintenance branch must be merged up to master:

```
$ git checkout master
$ git pull mongodb master
$ git merge vX.Y --strategy=ours
$ git push
$ git push mongodb
```

The `--strategy=ours` option ensures that all changes from the merged commits
will be ignored.
will be ignored. This is OK because we previously ensured that the `master`
branch was up-to-date with all code changes in this maintenance branch before
tagging.

### Publish release notes

The following template should be used for creating GitHub release notes via
[this form](https://github.com/mongodb/mongo-php-driver/releases/new). The PECL
package may also be attached to the release notes.

```
```markdown
The PHP team is happy to announce that version X.Y.Z of the [mongodb](https://pecl.php.net/package/mongodb) PHP extension is now available on PECL.

**Release Highlights**

<one or more paragraphs describing important changes in this release>

A complete list of resolved issues in this release may be found at:
$JIRA_URL
A complete list of resolved issues in this release may be found in [JIRA]($JIRA_URL).

**Documentation**

Documentation is available on PHP.net:
https://www.php.net/set.mongodb
Documentation is available on [PHP.net](https://php.net/set.mongodb).

**Installation**

Expand All @@ -485,7 +518,7 @@ release. You may obtain the list from
If commits from community contributors were included in this release, append the
following section:

```
```markdown
**Thanks**

Thanks for our community contributors for X.Y.Z:
Expand Down