Updating Documents

Now that we have a document, it needs to stay up to date. This is the role of the Shepherd. At some point the shepherd should assess if a new version is required. Discussions on mailing lists, merge requests on the repository, etc. are indicators that a document requires a new version.

If there are no changes required to the document, the only thing to do is to update the date that the document was assessed, and bump the minor version of the document (see Versioning).

Otherwise, the process for getting a new version of a BCP document contains of the following steps:

Depending on the quantity of the changes, the work can be done on the main branch, or in a newly created branch.
Per discussion topic, a GitLab isue can be created.
Per GitLab issue, a merge request can be created that should resolve the issue.
The merge request should be reviewed by the community, and once there is consensus the shepherd can merge the document changes. This will automatically trigger a new build of the “Read the Docs” page.
At some point the changed document becomes the new version.

A New Branch

It is not set in stone whether the new work needs to be done in a separate, newly created branch, or can be done on the main branch. Both ways have its merits.

The Shepherd may decide to create a new branch. It should have a meaningful name. This can be done at New branch or via the command line with:

git checkout -b version-2.0
git push -u origin version-2.0

The branch to work on should be announced to the OARC community.

Discussion Topics

There is likely going to be discussion about the BCP documents. The Shepherd should make sure these are captured in GitLab issues.

To create a new issue, go to Issues and click on the New item button.

On the page fill in the following details:

Type
Set to Issue. The other values may be assigned to have different types of change requests in the future.

Title
Set to something short but meaningful.

Description
Capture the discussion, what is the problem with the current version of the document, and what the desired outcome is.

Assignee
By default, assign to the Shepherd, but it can also be someone else (volunteering).

Labels
Unused for now.

Milestone
Unused for now.

Dates
Unused for now.

Contacts
Unused for now.

There should not be a reason to turn on confidentiality on the issue, so leave the checkbox unchecked. Then click on the Create issue button.

Issues may be created at any time during the process of updating the document. Issues may be reopened if after closing new matters arise. Alternatively, a new issue may be created to cover the new considerations.

Merge Requests

Anyone can create a merge request. This requires a fork of the project.

Once you have your own fork, you can create new development branches and make changes to the document. Once satisfied, you can push these branches and request a merge.

Fork Project

To fork the project, go to the project page and click on Fork. On the page, fill in the following:

Project name
Leave as is.

Project URL
Set to https://gitlab.com/<namespace>, where <namespace> is your personal GitLab space.

Project slug
Leave as is.

Project description
Optional and free form.

Branches to include
Select All branches (because updating a document may happen in an other branch than main).

Visibility level
Select Public.

Then click on the Fork project button.

Create Working Branch

Now that you have a fork of the project, you can clone the fork and create working branches. On the commandline type:

git clone git@gitlab.com:<namespace>/0000-howto-bcp.git
git checkout -b issue-1-fix-typos version-2.0

This creates a new working branch issue-1-fix-typos targeted at the version-2.0 branch.

Now you can do some work, and once satisfied, you can push the branch upstream:

git push -u origin issue-1-fix-typos

Create Merge Request

Now that your branch is available upstream, you can create a merge request against the project. Go to New merge request and set the Source branch to issue-1-fix-typos (following the example above) and click on Compare branches and continue.

This will fill in the Title and Description that can be adjusted. You can add “Closes #1” to the desription if the changes resolve an issue (in this case issue 1).

Furthermore, set the following:

Assignee
Set to the Shepherd.

Reviewer
Leave unassigned.

Milestone
Unused for now.

Labels
Unused for now.

Merge can start
Select Anytime.

Merge options
Leave “Delete source branch when merge request is accepted” checked. Leave “Squash commits when merge request is accepted” unchecked.

Contribution
Leave this checkbox checked.

Then click on Create merge request. Your changes are now ready for review.

Reviewing

Anyone can review the changes. Discussions should happen on the merge request.

Changes can be made and should be made as fixup commits, so it is clear what has changed after the initial merge request. A fixup commit can be made with

git commit --fixup <commit>

Once the reviewers are satisfied with all the changes, they should push the Approve button. This gives an idea on consensus, the more approvals the more clear it is for the shepherd that the changes are accepted by the community.

Before merging, all the fixup commits should be squashed into the right commit. This is done with a rebase:

git rebase -i --autosquash

The role_shepherd should make sure the changes are reviewed (there are one or more approvals), and that there is no disagreement on the issue (there are no open comments on the merge request and corresponding issue).

If that all is true, the shepherd may merge the request. The corresponding issue is automatically closed if the description contained “Closes #<issue>” with <issue> being the issue number.

If there is no work left to be done, it is time to create a new version of the document.

Versioning

A document should be assessed at least once a year. It could be that the assessment leads to no change. If a document does lead to a new change, the document version should be updated. Add the following text to the note in ``index.rst`.

Version
The new version. Bump the patch level (rightmost number) by one if there are no document changes (but the metadata). Otherwise bump the major version (leftmost number) by one.

Shepherd
The Shepherd fills in their name.

Latest assessment
The date when the new version is created (likely today), in YYYY-MM-DD format.

For example:

Version: 0.1.1

Shepherd: Matthijs Mekking

Latest assessment: 2026-01-20

Now this change can be committed, tagged, and pushed upstream.

git add index.rst
git commit -m "Set version to 0.1.1"
git tag -a 0.1.1 -m 'version 0.1.1'
git push -u --tags origin

Finally, the version needs to be activated. Go to the Read the Docs dashboard and click on Add version. There should be a dropbox with all tagged versions. Select the right version number and then click Update version. You should see the new version has appeared in the list of versions, with a build in process.

Stable versions

When there is a stable version of the document, and a new version is under construction, it is recommended to point users to the stable version of the document. Go to the Read the Docs settings and select stable as the Default branch, then click on the Save button.

The stable version maps to the most recent semantic tag.

This defaults to latest, but another common configuration is setting it to your stable version.

Minor versions

Minor version numbers are currently unused, but can be added if there are minimal changes to the document.