Juju documentation, found online at https://jujucharms.com/docs
The documentation is written in Markdown, and then generated into HTML.
The latest version of these docs live at:
For advice on contributing to the docs (please!), see
the contributing.html page in
this project. This has important information on style, the use of Markdown and
other useful tips.
For editing actual documentation, you will find the Markdown format source
files in the src/en directory. At some point we hope to offer multilingual
versions of the docs, whereupon these will live in similarly titled directories
(e.g. ‘fr’, ‘de’, etc.).
There are two other files in the src directory:
navigation.tpl - This is used to build the navigation for the website. You
won’t need to change this unless you are adding a new page (and even then,
please ask about where it should go).
base.tpl - this is the HTML template local docs use. This is as far as
possible a simulation of how the docs appear online, but changes to this file
do not alter the online appearance of the docs.
The htmldocs directory is where local builds of the docs are made, and
contains some support files (CSS, JavaScript) and all the graphics used by the
docs. If you need to add graphics, add them here (htmldocs/media).
NOTE! Please don’t replace graphics unless you know what you are doing.
These image files are used by all versions of the docs, so usually you will want
to add files rather than change existing ones, unless the changes apply to all
versions of Juju (e.g. website images).
The tools directory is reserved for build tools and support files.
The versions file contains a list of Github branches which represent the
current supported versions of documentation. Many tools rely on this list, it
should not be changed by anyone but the docs team!
The archive file contains a list of Github branches which contain unmaintained,
older versions of documentation.
The Makefile is used to build local versions of the docs, and other useful
things. Some of the make targets are:
tools/mdtool.py program to build a local version of theGithub, and git, allow you to use many different styles of workflow, but it is
tricky to get your head around initially, so here is an example of how to use it
easily for our documentation.
Make sure you have a Github account! https://github.com/join
Fork the juju/docs Github repository. This
creates your own version of the repository (which you can then find online at
https://github.com/{yourusername}/docs)
Create a local copy:
git clone https://github.com/{yourusername}/docs
cd docs
Add a git remote to your local repository. This links it with the ‘upstream’
version of the documentation, which makes it easier to update your fork and
local version of the docs:
git remote add upstream https://github.com/juju/docs
Create a ‘feature branch’ to add your content/changes
git checkout -b {branchname}
Edit files and make changes in this branch. You can use the command:
git status
to check which files you have added or edited. For each of these you will
need to explicitly add the files to the repository. For example:
git add src/en/about-juju.md
git add htmldocs/media/about-charms.jpg
If you wish to move or rename files you need to use the git mv command, and
the git rm command to delete them
To ‘save’ your changes locally, you should make a commit:
git commit -m 'my commit message which says something useful'
Check that the changes you have made make sense! You can build a local
version of the docs ( make && make serve) to check it renders
properly.
Push the branch back to your fork on Github
git push origin {branchName}
Do not be alarmed if you are asked for your username/password, it is part of
the authentication, though you can make things easier by any of:
Create a pull request. This is easily done in the web interface of Github:
navigate to your branch on the web interface and hit the compare button -
this will allow you to compare across forks to the juju/docs master branch,
which is where your changes will hopefully end up. The comparison will show
you a diff of the changes - it is useful to look over this to avoid
mistakes. Then click on the button to Create a pull request.
Add any useful info about the changes in the comments (e.g. if it fixes an
issue you can refer to it by number to automatically link your pull request
to the issue)
Wait. The documentation team will usually get to your pull request within a
day or two. Be prepared for suggested changes and comments. If there are
changes to be made:
git commit -m 'some message' to commit the new changesgit push origin {branchname}Once the code has been landed you can remove your feature branch from both the
remote and your local fork. Github provides a button for this at the bottom of
the pull request, or you can use git to remove the branch.
Before creating another feature branch, make sure you update your fork’s code
by pulling from the original Juju repository (see below).
You should now have both the upstream branch and your fork listed in git,
git remote -v should return something like:
upstream https://github.com/juju/docs.git (fetch)
upstream https://github.com/juju/docs.git (push)
origin https://github.com/castrojo/docs (fetch)
origin https://github.com/castrojo/docs (push)
To fetch and merge with the upstream branch:
git checkout master
git fetch upstream
git merge --ff-only upstream/master
git push origin master
Git Remote Branch - A tool to
simplify working with remote branches (Detailed installation instructions are
in their README).
Git provides a mechanism for creating aliases for complex or multi-step
commands. These are located in your .gitconfig file under the
[alias] section.
If you would like more details on Git aliases, You can find out more
information here: How to add Git aliases
Below are a few helpful aliases that have been suggested:
# Bring down the pull request number from the remote specified.
# Note, the remote that the pull request is merging into may not be your
# origin (your github fork).
fetch-pr = "!f() { git fetch $1 refs/pull/$2/head:refs/remotes/pr/$2; }; f"
# Make a branch that merges a pull request into the most recent version of the
# trunk (the "juju" remote's develop branch). To do this, it also updates your
# local develop branch with the newest code from trunk.
# In the example below, "juju" is the name of your remote, "6" is the pull
# request number, and "qa-sticky-headers" is whatever branch name you want
# for the pull request.
# git qa-pr juju 6 qa-sticky-headers
qa-pr = "!sh -c 'git checkout develop; git pull $0 develop; git checkout -b $2; git fetch-pr $0 $1; git merge pr/$1'"