-
Notifications
You must be signed in to change notification settings - Fork 340
Documenting
Summary
- The official MaxScale documentation resides in the MariaDB Knowledge Base.
- The Knowledge Base content is pulled from the MaxScale-Documentation repository.
- During development, the documentation is written and updated in the Documentation directory in the MaxScale repository.
- At release time, the Documentation directory in MaxScale is pushed using
git subtreeto MaxScale-Documentation. - Between releases, in case there is an urgent need to make a correction to the documentation, MaxScale-Documentation is updated directly. Subsequently, the Documentation directory of the develop branch in MaxScale is updated using
git subtree pull. - Whenever MaxScale-Documentation is updated, the Knowledge Base content must be pulled anew.
The documentation in the Documentation directory is updated just as if it would be a a regular directory in the repository (which it indeed actually is).
Typically the documentation modifications are done in the same commit where the corresponding source code modifications are made.
When a release has been frozen and the the tag has been created in the MaxScale repository, the Documentation subtree should be pushed to the MaxScale-Documentation repository, to a branch whose name corresponds to the tag.
For instance, suppose release 1.X.Y is being released. In the MaxScale repository, the final adjustments have taken place in the release-1.X.Y branch. When all is finalized, the tag 1.X.Y is created. At that point, the Documentation directory is pushed as follows:
$ cd MaxScale
$ git checkout 1.X.Y
$ git subtree push -P Documentation\
[email protected]:mariadb-corporation/MaxScale-Documentation.git release-1.X.Y
Then move to the MaxScale-Documentation repository and create the corresponding tag.
$ cd MaxScale-Documentation
$ git fetch
$ git checkout release-1.X.Y
$ git tag -a 1.X.Y
$ git push --tags
NOTE: No only purpose of the tag in the MaxScale-Documentation repository is to make it easy to later figure out what in-between releases modifications have been made.
At this point, the maintainer of the MariaDB Knowledge Base should be asked to update the Knowledge Base MaxScale documentation from [email protected]:mariadb-corporation/MaxScale-Documentation.git using the branch release-1.X.Y.
NOTE: The KB documentation is taken using the branch release-1.X.Y and not the tag 1.X.Y.
If a mistake that needs to be corrected is noticed in the documentation, that correction is now done directly in the MaxScale-Documentation repository.
$ git clone [email protected]:mariadb-corporation/MaxScale-Documentation.git
$ cd MaxScale-Documentation
$ git checkout release-1.X.Y
$ # Edit and fix the mistake.
$ git push origin release-1.X.Y
At this point, the maintainer of the MariaDB Knowledge Base should be asked to update the Knowledge Base MaxScale documentation using the same branch he previously used, that is, release-1.X.Y.
The changes made in MaxScale-Documentation should now be pulled to the development branch in the MaxScale repository. That ensures that the corrections are included in the documentation of the next release of MaxScale.
$ cd MaxScale
$ git checkout develop
$ git subtree pull -P Documentation \
[email protected]:mariadb-corporation/MaxScale-Documentation.git release-1.X.Y
When a release has been made, the source is frozen and can no longer be changed (without another release). Consequently, the source of a release in the MaxScale repository is marked with a tag (which can be moved, but we do not do that).
However, the documentation of a release can change after it has been released - explanations can be clarified and mistakes be corrected - and consequently the documentation of a release is identified with a branch; the tip of the release specific branch identifies the most up to date documentation.
If a tag were used, it would either have to be moved after each correction or then a new tag would have to be created for each correction, which would increase the maintenance burden (also at the Knowledge Base side), for no good reason.