7100ab2cd8
A list of things to check when reviewing documentation changes is added to README. Separate build commands for release notes are no longer relevant, release notes are now generated together with all other documents. Change-Id: I19d39ddb63cda5594a82a968c7f2f2ad894d444f
144 lines
4.6 KiB
Markdown
144 lines
4.6 KiB
Markdown
|
|
Mirantis OpenStack Documentation
|
|
=================================
|
|
|
|
This repository contains the Mirantis OpenStack user and administrator
|
|
guides. For more details, see the [Mirantis OpenStack
|
|
portal](http://software.mirantis.com "Mirantis OpenStack portal").
|
|
|
|
Contributing
|
|
============
|
|
|
|
We welcome all people who are interested in helping our Documentation team
|
|
to improve our documentation. There are no formal membership requirements,
|
|
so feel free to hop in. The best way to contibute is to fork our repository,
|
|
do your changes and send us a Pull Request. You are invited to contribute
|
|
any type of contribution like new ideas, testing, and even deployment scripts.
|
|
|
|
We also have an IRC channel at ``#fuel`` & ``#fuel-dev`` on ``irc.freenode.net``
|
|
where you can ask questions and give feedback.
|
|
|
|
Prerequisites
|
|
=============
|
|
|
|
[Sphinx Documentation Generator](http://sphinx-doc.org/ "Sphinx
|
|
Documentation Generator") must be installed to build the documentation.
|
|
Please note that easy_install is a component of Python's Setup Tools
|
|
package, which is commonly an optional install on most distributions.
|
|
|
|
|
|
To get started, you need to install all necesasary tools:
|
|
|
|
sudo apt-get install git python-pip python-dev make imagemagick libjpeg-dev inkscape
|
|
|
|
Among other things that installs
|
|
[ImageMagick](http://www.imagemagick.org/ "ImageMagick") and
|
|
[Inkscape](http://inkscape.org/ "Inkscape").
|
|
|
|
And Sphinx necessary extensions:
|
|
|
|
sudo pip install -r requirements.txt
|
|
|
|
In addition to these eggs you will need to install
|
|
[PlantUML](http://plantuml.sourceforge.net/ "PlantUML")
|
|
|
|
To install PlantUML run this wget process:
|
|
|
|
sudo wget \
|
|
http://sourceforge.net/projects/plantuml/files/plantuml.jar/download \
|
|
-O /sbin/plantuml.jar
|
|
|
|
PlantumUML requires java:
|
|
sudo apt-get install openjdk-7-jre
|
|
|
|
We use [Inkscape](http://inkscape.org/ "Inkscape") to edit SVG images
|
|
and convert them to PDF but you may use any other SVG-capable tool you
|
|
like. We're not picky.
|
|
|
|
Building
|
|
========
|
|
|
|
To build a guide in HTML format, go to its directory and then run the
|
|
``make`` command in that directory, like so:
|
|
|
|
make html
|
|
|
|
To generate the PDF file run this:
|
|
|
|
make pdf
|
|
|
|
You will find generated HTML documentation at:
|
|
|
|
_build/html
|
|
|
|
You will find generated PDF documentation at:
|
|
|
|
_build/pdf
|
|
|
|
Reviewer's Checklist
|
|
====================
|
|
|
|
Checks for commit message:
|
|
|
|
1. The goal and extent of the change should be described in the commit
|
|
message.
|
|
|
|
2. If the commit is related to a LaunchPad bug, it should have
|
|
"Closes-Bug: nnnnnnn" line in the commit message. Likewise,
|
|
"blueprint name-of-the-blueprint" for a commit related to a
|
|
blueprint. Most non-trivial commits should have such references.
|
|
|
|
Checks for content changes:
|
|
|
|
1. For every block of content that is removed, there should be either a
|
|
block that replaces it, or an explanation in the commit message why
|
|
that block is no longer needed.
|
|
|
|
2. Confirm that the new content is approved by a technical expert in the
|
|
relevant area.
|
|
|
|
3. Check that the content is in the right document and the right
|
|
context. Deployment of Fuel itself is described in the Installation
|
|
Guide; deployment of Mirantis OpenStack using Fuel, in User Guide;
|
|
post-deployment operation of Mirantis OpenStack, in Operations Guide;
|
|
and so on.
|
|
|
|
Checks for structural changes:
|
|
|
|
1. For any removed file (including original path in a move or rename),
|
|
grep for the file name through all rst files and confirm that no
|
|
stale references to the file are left behind.
|
|
|
|
2. For any added file (including new path in a move or rename), confirm
|
|
that the new path is referenced in a way that will get it included in
|
|
at least one document.
|
|
|
|
Testing the change locally:
|
|
|
|
1. Download the branch:
|
|
git review -d <gerrit-id>
|
|
|
|
2. Check that it's based on the current tip of the master branch, look
|
|
for "origin/master" next to commit hash in the output of:
|
|
git log --graph --decorate
|
|
|
|
3. If it's not, check if it can be rebased onto master cleanly:
|
|
git rebase --onto master HEAD^
|
|
|
|
4. Build HTML and PDF versions as described above. If rebase was
|
|
necessary, build from the rebased version: you want to see what the
|
|
result of the merge into master will look like
|
|
|
|
5. Check that the count of warnings reported by 'make pdf' hasn't
|
|
increased relative to master.
|
|
|
|
6. Check that all sections touched by the change show up in the table of
|
|
contents in the right place and at the right nesting level.
|
|
|
|
Finally, go through all changes line by line and ask yourself: what is
|
|
the purpose of this change? Is that related to the description of the
|
|
review given in the commit message? Could it be accidental or result of
|
|
a merge error during rebase?
|
|
|
|
|