Skip to content

Documentation/tooling tweaks from the 3.8.1 release #1033

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 4 commits into from
Oct 9, 2023
Merged

Documentation/tooling tweaks from the 3.8.1 release #1033

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
1f420bb
Update versions, clarify some release docs
vector-of-bool Sep 5, 2023
692a7b2
Remove no-longer-applicable release step
vector-of-bool Oct 5, 2023
f515600
New release docs in perl script
vector-of-bool Oct 5, 2023
b1ac0a2
Fix release step ordering
vector-of-bool Oct 5, 2023
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
2 changes: 1 addition & 1 deletion .evergreen/spec.patch
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
+
Name: mongo-cxx-driver
-Version: 3.6.5
+Version: 3.8.0
+Version: 3.8.1
Release: 1%{?dist}
Summary: A C++ Driver for MongoDB
License: ASL 2.0
Expand Down
2 changes: 1 addition & 1 deletion debian/libbsoncxx-noabi.lintian-overrides
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,4 @@
libbsoncxx-noabi: no-symbols-control-file

# False positive on the spelling error
libbsoncxx-noabi: spelling-error-in-binary ment meant [usr/lib/x86_64-linux-gnu/libbsoncxx.so.3.8.0]
libbsoncxx-noabi: spelling-error-in-binary ment meant [usr/lib/x86_64-linux-gnu/libbsoncxx.so.3.8.1]
2 changes: 1 addition & 1 deletion docs/content/mongocxx-v3/installation/advanced.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ The above command would produce libraries named `libcustom_bsoncxx.so` and `libc

The mongocxx driver builds on top of the [MongoDB C driver](https://www.mongodb.com/docs/drivers/c/).

The build of mongocxx-3.8.0 automatically downloads and installs the C driver if the C driver is not detected.
The build of mongocxx-3.8.1 automatically downloads and installs the C driver if the C driver is not detected.
To use an existing install of the C driver, set `CMAKE_PREFIX_PATH` to the directory containing the C driver install.

* For mongocxx-3.8.x, libmongoc 1.24.0 or later is required.
Expand Down
8 changes: 4 additions & 4 deletions docs/content/mongocxx-v3/installation/linux.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,12 +50,12 @@ release tarball.

The [mongocxx releases](https://github.com/mongodb/mongo-cxx-driver/releases)
page will have links to the release tarball for the version you wish you install. For
example, to download version 3.8.0:
example, to download version 3.8.1:

```sh
curl -OL https://github.com/mongodb/mongo-cxx-driver/releases/download/r3.8.0/mongo-cxx-driver-r3.8.0.tar.gz
tar -xzf mongo-cxx-driver-r3.8.0.tar.gz
cd mongo-cxx-driver-r3.8.0/build
curl -OL https://github.com/mongodb/mongo-cxx-driver/releases/download/r3.8.1/mongo-cxx-driver-r3.8.1.tar.gz
tar -xzf mongo-cxx-driver-r3.8.1.tar.gz
cd mongo-cxx-driver-r3.8.1/build
```

Make sure you change to the `build` directory of whatever source tree you
Expand Down
8 changes: 4 additions & 4 deletions docs/content/mongocxx-v3/installation/macos.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,12 +50,12 @@ release tarball.

The [mongocxx releases](https://github.com/mongodb/mongo-cxx-driver/releases)
page will have links to the release tarball for the version you wish you install. For
example, to download version 3.8.0:
example, to download version 3.8.1:

```sh
curl -OL https://github.com/mongodb/mongo-cxx-driver/releases/download/r3.8.0/mongo-cxx-driver-r3.8.0.tar.gz
tar -xzf mongo-cxx-driver-r3.8.0.tar.gz
cd mongo-cxx-driver-r3.8.0/build
curl -OL https://github.com/mongodb/mongo-cxx-driver/releases/download/r3.8.1/mongo-cxx-driver-r3.8.1.tar.gz
tar -xzf mongo-cxx-driver-r3.8.1.tar.gz
cd mongo-cxx-driver-r3.8.1/build
```

Make sure you change to the `build` directory of whatever source tree you
Expand Down
8 changes: 4 additions & 4 deletions docs/content/mongocxx-v3/installation/windows.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -50,12 +50,12 @@ release tarball.

The [mongocxx releases](https://github.com/mongodb/mongo-cxx-driver/releases)
page will have links to the release tarball for the version you wish you install. For
example, to download version 3.8.0:
example, to download version 3.8.1:

```sh
curl -OL https://github.com/mongodb/mongo-cxx-driver/releases/download/r3.8.0/mongo-cxx-driver-r3.8.0.tar.gz
tar -xzf mongo-cxx-driver-r3.8.0.tar.gz
cd mongo-cxx-driver-r3.8.0/build
curl -OL https://github.com/mongodb/mongo-cxx-driver/releases/download/r3.8.1/mongo-cxx-driver-r3.8.1.tar.gz
tar -xzf mongo-cxx-driver-r3.8.1.tar.gz
cd mongo-cxx-driver-r3.8.1/build
```

Make sure you change to the `build` directory of whatever source tree you
Expand Down
91 changes: 46 additions & 45 deletions etc/apidocmenu.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,54 +5,55 @@
Stability indicates whether this driver is recommended for production use.
Currently, no drivers guarantee API or ABI stability.

| Family/version | Stability | Development | Purpose |
| -------------------- | ----------- | ------------------- | ------------------------------------- |
| (repo master branch) | Unstable | Active development | New feature development |
| mongocxx 3.8.x | Stable | Bug fixes only | Current stable C++ driver release |
| mongocxx 3.7.x | Stable | None | Previous stable C++ driver release |
| mongocxx 3.6.x | Stable | None | Previous stable C++ driver release |
| mongocxx 3.5.x | Stable | None | Previous stable C++ driver release |
| mongocxx 3.4.x | Stable | None | Previous stable C++ driver release |
| mongocxx 3.3.x | Stable | None | Previous stable C++ driver release |
| mongocxx 3.2.x | Stable | None | Previous stable C++ driver release |
| mongocxx 3.1.x | Stable | None | Previous stable C++ driver release |
| mongocxx 3.0.x | Stable | None | Previous stable C++ driver release |
| Family/version | Stability | Development | Purpose |
| -------------------- | --------- | ------------------ | ---------------------------------- |
| (repo master branch) | Unstable | Active development | New feature development |
| mongocxx 3.8.x | Stable | Bug fixes only | Current stable C++ driver release |
| mongocxx 3.7.x | Stable | None | Previous stable C++ driver release |
| mongocxx 3.6.x | Stable | None | Previous stable C++ driver release |
| mongocxx 3.5.x | Stable | None | Previous stable C++ driver release |
| mongocxx 3.4.x | Stable | None | Previous stable C++ driver release |
| mongocxx 3.3.x | Stable | None | Previous stable C++ driver release |
| mongocxx 3.2.x | Stable | None | Previous stable C++ driver release |
| mongocxx 3.1.x | Stable | None | Previous stable C++ driver release |
| mongocxx 3.0.x | Stable | None | Previous stable C++ driver release |

## Documentation versions available

| mongocxx |
| ---------------------------------------------|
| [mongocxx-3.8.0](../mongocxx-3.8.0) |
| [mongocxx-3.7.2](../mongocxx-3.7.2) |
| [mongocxx-3.7.1](../mongocxx-3.7.1) |
| [mongocxx-3.7.0](../mongocxx-3.7.0) |
| [mongocxx-3.6.7](../mongocxx-3.6.7) |
| [mongocxx-3.6.6](../mongocxx-3.6.6) |
| [mongocxx-3.6.5](../mongocxx-3.6.5) |
| [mongocxx-3.6.4](../mongocxx-3.6.4) |
| [mongocxx-3.6.3](../mongocxx-3.6.3) |
| [mongocxx-3.6.2](../mongocxx-3.6.2) |
| [mongocxx-3.6.1](../mongocxx-3.6.1) |
| [mongocxx-3.6.0](../mongocxx-3.6.0) |
| [mongocxx-3.5.1](../mongocxx-3.5.1) |
| [mongocxx-3.5.0](../mongocxx-3.5.0) |
| [mongocxx-3.4.2](../mongocxx-3.4.2) |
| [mongocxx-3.4.1](../mongocxx-3.4.1) |
| [mongocxx-3.4.0](../mongocxx-3.4.0) |
| [mongocxx-3.3.2](../mongocxx-3.3.2) |
| [mongocxx-3.3.1](../mongocxx-3.3.1) |
| [mongocxx-3.3.0](../mongocxx-3.3.0) |
| [mongocxx-3.2.1](../mongocxx-3.2.1) |
| [mongocxx-3.2.0](../mongocxx-3.2.0) |
| [mongocxx-3.1.4](../mongocxx-3.1.4/) |
| [mongocxx-3.1.3](../mongocxx-3.1.3/) |
| [mongocxx-3.1.2](../mongocxx-3.1.2/) |
| [mongocxx-3.1.1](../mongocxx-3.1.1/) |
| [mongocxx-3.1.0](../mongocxx-3.1.0/) |
| [mongocxx-3.0.3](../mongocxx-3.0.3/) |
| [mongocxx-3.0.2](../mongocxx-3.0.2/) |
| [mongocxx-3.0.1](../mongocxx-3.0.1/) |
| [mongocxx-3.0.0](../mongocxx-3.0.0/) |
| mongocxx |
| ------------------------------------ |
| [mongocxx-3.8.1](../mongocxx-3.8.1) |
| [mongocxx-3.8.0](../mongocxx-3.8.0) |
| [mongocxx-3.7.2](../mongocxx-3.7.2) |
| [mongocxx-3.7.1](../mongocxx-3.7.1) |
| [mongocxx-3.7.0](../mongocxx-3.7.0) |
| [mongocxx-3.6.7](../mongocxx-3.6.7) |
| [mongocxx-3.6.6](../mongocxx-3.6.6) |
| [mongocxx-3.6.5](../mongocxx-3.6.5) |
| [mongocxx-3.6.4](../mongocxx-3.6.4) |
| [mongocxx-3.6.3](../mongocxx-3.6.3) |
| [mongocxx-3.6.2](../mongocxx-3.6.2) |
| [mongocxx-3.6.1](../mongocxx-3.6.1) |
| [mongocxx-3.6.0](../mongocxx-3.6.0) |
| [mongocxx-3.5.1](../mongocxx-3.5.1) |
| [mongocxx-3.5.0](../mongocxx-3.5.0) |
| [mongocxx-3.4.2](../mongocxx-3.4.2) |
| [mongocxx-3.4.1](../mongocxx-3.4.1) |
| [mongocxx-3.4.0](../mongocxx-3.4.0) |
| [mongocxx-3.3.2](../mongocxx-3.3.2) |
| [mongocxx-3.3.1](../mongocxx-3.3.1) |
| [mongocxx-3.3.0](../mongocxx-3.3.0) |
| [mongocxx-3.2.1](../mongocxx-3.2.1) |
| [mongocxx-3.2.0](../mongocxx-3.2.0) |
| [mongocxx-3.1.4](../mongocxx-3.1.4/) |
| [mongocxx-3.1.3](../mongocxx-3.1.3/) |
| [mongocxx-3.1.2](../mongocxx-3.1.2/) |
| [mongocxx-3.1.1](../mongocxx-3.1.1/) |
| [mongocxx-3.1.0](../mongocxx-3.1.0/) |
| [mongocxx-3.0.3](../mongocxx-3.0.3/) |
| [mongocxx-3.0.2](../mongocxx-3.0.2/) |
| [mongocxx-3.0.1](../mongocxx-3.0.1/) |
| [mongocxx-3.0.0](../mongocxx-3.0.0/) |

## MongoDB compatibility

Expand Down
1 change: 1 addition & 0 deletions etc/generate-all-apidocs.pl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,7 @@ sub _try_run {
r3.7.1
r3.7.2
r3.8.0
r3.8.1
);

sub main {
Expand Down
71 changes: 33 additions & 38 deletions etc/releasing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,21 +74,22 @@ pip install -r etc/requirements.txt

## Tag the release

If doing a minor release (e.g. releasing r3.8.0), stay on the master branch. You
will create a new `releases/v3.8` branch later in the instructions. If doing a
patch release (e.g. releasing r3.7.3), check out the corresponding release
branch, which should be the existing `releases/v3.7` branch.
If doing a minor release (e.g. releasing r1.2.0, with a zero patch component),
stay on the master branch. You will create a new `releases/vX.Y` branch later in
the instructions. If doing a patch release (e.g. releasing rX.Y.Z with non-zero
`Z`), check out the corresponding release branch, which should be an existing
`releases/vX.Y` branch.

Create a tag for the commit to serve as the release (or release candidate):

```
git tag r3.8.0
git tag r1.2.3
```

## Run make_release.py

`make_release.py` creates the distribution tarball
(e.g. mongo-cxx-driver-r3.8.0.tar.gz), interacts with Jira, and drafts the
(e.g. mongo-cxx-driver-r1.2.3.tar.gz), interacts with Jira, and drafts the
release on GitHub.

To see all available options, run with `--help`
Expand All @@ -113,7 +114,7 @@ python ./etc/make_release.py \
--dry-run \
--jira-creds-file ~/.secrets/jira_creds.txt \
--github-token-file ~/.secrets/github_token.txt \
r3.8.0
r1.2.3
```

If all goes well, run the command again without `--dry-run`, which should build
Expand All @@ -130,15 +131,15 @@ follows:
- Use `--skip-distcheck` to bypass time consuming checks when building the
distribution tarball.
- If the script succeeded at creating the distribution tarball, pass it directly
with `--dist-file ./build/mongo-cxx-driver-r3.8.0.tar.gz`.
with `--dist-file ./build/mongo-cxx-driver-r1.2.3.tar.gz`.

## Push the tag

Review the build output and, assuming the distcheck target is successful, push
the tag:
the tag into the main remote:

```
git push origin r3.8.0
git push [email protected]:mongodb/mongo-cxx-driver.git refs/tags/r1.2.3
```

### Release the Version in GitHub
Expand Down Expand Up @@ -167,7 +168,7 @@ to the repo:

```
git checkout releases/stable
git reset --hard r3.8.0
git reset --hard r1.2.3
git push -f origin releases/stable
```

Expand All @@ -181,15 +182,18 @@ pushed.
following the established pattern. If this is a minor release (x.y.0), revise
the entire document as needed.
- Edit `docs/content/_index.md` and `README.md` to match.
- Edit `etc/generate-all-apidocs.pl` and add the new release version to the
`@DOC_TAGS` array, following the established pattern.
- Edit the `Installing the MongoDB C driver` section of
`docs/content/mongocxx-v3/installation/advanced.md` to reflect libmongoc
requirements.
- Edit `docs/content/mongocxx-v3/installation/linux.md`,
`docs/content/mongocxx-v3/installation/macos.md` and
`docs/content/mongocxx-v3/installation/windows.md` and update `Step 1` to
reflect to libmongoc requirements. If the release was not a release candidate,
update `Step 3` to reflect the new latest stable version to download.
`docs/content/mongocxx-v3/installation/windows.md`.
If the release was not a release candidate, update `Step 2` to reflect the
new latest stable version to download.
- Edit `etc/generate-all-apidocs.pl` and add the new release version to the
`@DOC_TAGS` array, following the established pattern.
- Commit these changes:
`git commit -am "Prepare to generate r3.8.0 release documentation"`
`git commit -am "Prepare to generate r1.2.3 release documentation"`
- Ensure you have `doxygen` and `hugo` installed and up to date.
- Run `git clean -dxf` to clear out all extraneous files.
- Configure with `cmake` in the `build` directory as you usually would.
Expand All @@ -206,27 +210,19 @@ pushed.
- `cmake --build ./build --target doxygen-deploy`
- If the release was not a release candidate, update symlinks
- Check out the `gh-pages` branch and git pull the deployed docs.
- Update the `api/mongocxx-v3` symlink to point to the newly released
version. If a major version bump has occurred, revise the symlink structure
as needed. Make sure `current` always points to a symlink tracking the
latest stable release branch.
- Update the `api/mongocxx-v3` symlink to point to the newly released version.
If a minor version bump has occurred, revise the symlink structure as
needed. Make sure `current` always points to a symlink tracking the latest
stable release branch.
- Commit and push the symlink change:
`git commit -am "Update symlink for r3.8.0"`
`git commit -am "Update symlink for r1.2.3"`
- Wait a few minutes and verify mongocxx.org has updated.
- Checkout the master branch. Push the commit containing changes to `etc/` and
`docs/`. This may require pushing the commit to a fork of the C++ Driver
repository and creating a pull request.
- Edit the `Installing the MongoDB C driver` section of
`docs/content/mongocxx-v3/installation/advanced.md` to reflect libmongoc
requirements.
- Edit `docs/content/mongocxx-v3/installation/linux.md`,
`docs/content/mongocxx-v3/installation/macos.md` and
`docs/content/mongocxx-v3/installation/windows.md`.
If the release was not a release candidate, update `Step 2` to reflect the
new latest stable version to download.

## Homebrew
This requires a macOS machine.
This requires a macOS machine.
If this is a stable release, update the [mongo-cxx-driver](https://github.com/Homebrew/homebrew-core/blob/master/Formula/mongo-cxx-driver.rb) homebrew formula, using: `brew bump-formula-pr --url <tarball url>`

Example:
Expand Down Expand Up @@ -255,7 +251,7 @@ of a release candidate of 3.6.0.

## Branch if necessary

If doing a new minor release `x.y` (e.g. a `3.8.0` release), create branch
If doing a new minor release `x.y.0` (e.g. a `1.2.0` release), create branch
`releases/vx.y` (e.g `releases/v3.8`).

Push the new branch:
Expand Down Expand Up @@ -452,12 +448,11 @@ patch --dry-run -d .evergreen -p0 -i spec.patch
```

- If the patch command fails, rebase the patch
- For a new major release (e.g., 3.6.0, 3.7.0, etc.), then ensure that the patch
updates the `up_version` to be the NEXT major version
(e.g., when releasing 3.7.0, the spec patch should update `up_version` to 3.8.0);
this is necessary to ensure that the spec file matches the tarball created by
the dist target; if this is wrong, then the `rpm-package-build` task will fail
in the next step
- For a new minor release (e.g., 3.6.0, 3.7.0, etc.), then ensure that the patch
updates the `up_version` to be the NEXT minor version (e.g., when releasing
1.2.0, the spec patch should update `up_version` to 1.3.0); this is necessary
to ensure that the spec file matches the tarball created by the dist target;
if this is wrong, then the `rpm-package-build` task will fail in the next step
- Additionally, ensure that any changes made on the release branch vis-a-vis the
spec file are also replicated on the `master` or `main` branch
- Test the build with something like this:
Expand Down