Ignite documentation sources are stored in the main Ignite repository together with the rest of the Ignite source code. The docs are written in the AsciiDoc format and transformed into the HTML form with the Jekyll toolchain. The published HTML version of the docs, that is accessible under the URL https://ignite.apache.org/docs/, is stored in the Ignite Website repository. The picture below explicates on how the things are tethered together:
The sections below cover the code contribution and publication processes in detail.
The documentation contribution process adheres to the main contribution process with several minor adjustments when it comes to the minor edits, fixing typos, or doing little corrections. For instance, while you always need to create a JIRA ticket for significant documentation changes and follow the main contribution process, with minor changes (such as typos correction) a committer can take a shortcut and commit a change to the repo without the need of having a respective JIRA ticket.
Under significant changes, we assume new features, notable rework on an existing documentation page, any other changes that require review by community members. Follow this process to contribute a significant documentation change:
Find documentation sources under the ignite_root/docs/_docs directory and do necessary modifications:
Do a grammar check of your changes. Use Grammarly if you don't have a more advanced tool at hand.
If you added a new page or imported any external files, run the license checker: `mvn clean validate -DskipTests=true -P check-licenses`
Send a pull-request, request the review from documentation maintainers.
Under the minor changes, we assume the fixing of typos, misprints, or easy-to-fix unclarities. In general, you're dealing with a minor change if it takes you a longer time to create a JIRA ticket and get a pull-request figured.
Only Ignite committers can go through this relaxed contribution process. Contributors need to follow Contributing Significant Changes.
Do the following to do a minor change:
Once an Ignite version is released, the release branch gets frozen and you won't be able to commit to it any changes (including documentation updates). This section explains how to update the docs in such conditions:
If you rename an already published page or change the page's path in the ignite_root/docs/_data/toc.yaml file, you must configure a proper redirect from the old to the new URL in the following files of the Ignite website:
https://github.com/apache/ignite-website/blob/master/.htaccess
Reach out to documentation maintainers if you need any help with this.
While the documentation sources are stored in the AsciiDoc format in the main Ignite repository, the version of the docs, that is published on the website, is stored in the Ignite website repo in the HTML format. This section explains how to publish documentation changes to the website.
Use the same command to generate an updated version of already released docs but do NOT specify the "–latest" flag:
./build.sh --version=2.8.0 --github-branch=IGNITE-2.8-docs
As for the rest, follow the procedure described in the Publishing New Version section above.
Docs Scope | Maintainers |
---|---|
All docs | Denis Magda (dmagda@apache.org) |
.NET-specific docs maintainers | Pavel Tupitsyn (ptupitsyn@apache.org) |
C++, Python, Node.JS, PHP-specific docs | Igor Sapego (isapego@gridgain.com) |