diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md index 60607825b..5f46ead88 100644 --- a/DOCUMENTATION.md +++ b/DOCUMENTATION.md @@ -103,7 +103,10 @@ Should a documentation page need to reference attributes, e.g. version numbers, The general rule is if an attribute changes frequently or is related to a specific version or subset of versions of Debezium, it likely belongs in the `antora.yml` file in this repository. If the attribute changes infrequent or is not specific to a given version of Debezium, its easier to maintain that in the various playbook files in the Debezium website repository. -Lets say we need to add an attribute that points to our JIRA issue for issue links, that would be an example of an attrbute that would be defined in the playbook. But if we needed to add an attribute that points to a specific version of a naven artifact or reference a specific version of a dependency, that's more appropriate for the `antora.yml` component descriptor located in this repository. +Lets say we need to add an attribute that points to our JIRA issue for issue links, +that would be an example of an attrbute that would be defined in the playbook. +But if we needed to add an attribute that points to a specific version of a Maven artifact or reference a specific version of a dependency, +that's more appropriate for the `antora.yml` component descriptor located in this repository. The current `antora.yml` component descriptor looks similar to the following: ``` @@ -138,32 +141,6 @@ asciidoc: **NOTE**: Given that the Debezium documentation is consumed downstream by other processes, do not define attributes in the `_attributes.adoc` file and use it as an include nor should you define attributes locally in a given .adoc file. -## What to change _before_ releasing a new version - -The `antora.yml` file in the `master` branch always uses version called _master_. It is important right before a release when applying the change log and contributor changes to modify this file to reference the correct major and minor version. It's also important to make any necessary changes to version-specific attributes in this file at the same time. - -So when releasing version 2.1 as an example, change `antora.yml` from: -``` -version: 'master' -``` -to -``` -version: '2.1' -``` - -## What to change _after_ releasing new version - -After the repository has been tagged, it is important to change the `antora.yml` back to _master_ and update any attributes post-release. - -So after releasing version 2.1 as an example, change `antora.yml` from: -``` -version: '2.1' -``` -to -``` -version: 'master' -``` - ## Contributing to the Documentation Follow these guidelines for contributing to the Debezium documentation. diff --git a/RELEASING.md b/RELEASING.md index 5ca4fc5ac..8ec6a1cd0 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -30,6 +30,21 @@ It currently exists in two versions, one in the main code repo and one on the we JIRA issues that break backwards compatability for existing consumers, should be marked with the "add-to-upgrade-guide" label. Search for them using [this query](https://issues.jboss.org/issues/?jql=labels%20%3D%20add-to-upgrade-guide) and describe the implications and required steps for upgrading in the changelog on the website. +## Update antora.yml + +The `antora.yml` file in the `master` branch always used the version _master_. +During the release process, this file's `version` attribute should be changed to reference the correct major/minor version number. +There are other Asciidoc variables defined here that should be reviewed and modified as needed. + +As an example, when releasing version `2.1`, the `antora.yml` file should change from: +``` +version: 'master' +``` +to +``` +version: '2.1' +``` + ## Start with the correct branch Make sure that you are on the correct branch that is to be released, and that your local Git repository has all of the most recent commits. For example, to release from the `master` branch on the remote repository named `upstream`: @@ -228,11 +243,14 @@ project=DBZ AND fixVersion= AND status='Resolved' ``` Then mark release in Jira as *Released* using `Release` action. +## Documentation post-release changes + +After the release, the `antora.yml` file should be changed so that the `version` attribute references `master` once more. + ## Update the documentation and blog Update the documentation on the [Debezium website](http://debezium.io) by following the [instructions for changing the website](http://debezium.io/docs/contribute/#website). This typically involves updating the documentation (look for pending pull requests tagged as "Merge after next release") and writing a blog post to announce the release. -Also update the `debezium-version` and `debezium-docker-label` attributes in _\_config/site.yml_. Then, create a pull request with your changes and wait for a committer to approve and merge your changes. When the blog post is available, use the [Debezium Twitter account](https://twitter.com/debezium) to announce the release by linking to the blog post.