Thanks for your interest in Juju -- contributions like yours make good projects great!
Whether it is code or docs, there are two basic ways to contribute: by opening an issue or by creating a PR. This document gives detailed information about both.
Note: If at any point you get stuck, come chat with us on Matrix.
You will need a GitHub account (sign up).
To open an issue for a specific doc, find the doc on RTD, then scroll to the bottom of the page, click on Open a GitHub issue for this page, edit the issue template that pops up, then submit.
To open an issue for docs in general, do the same for the homepage of the docs (i.e., use the link from the bottom of the RTD homepage or go to https://github.com/juju/juju/issues , click on New issue (top right corner of the page), select “Documentation issue”, then fill out the issue template and submit the issue.
Go to https://github.com/juju/juju/issues click on New issue (top right corner of the page), select whatever is appropriate, then fill out the issue template and submit the issue.
Note: For feature requests please use https://matrix.to/#/#charmhub-juju:ubuntu.com
You will need a GitHub account (sign up and add
your public SSH key) and git
(get
started).
Then:
-
Configure your
git
so your commits are signed:
git config --global user.name "A. Hacker"
git config --global user.email "[email protected]"
git config --global commit.gpgsign true
-
Fork juju/juju. This will create
https://github.com/<user>/juju
. -
Clone your fork locally.
git clone [email protected]:<user>/juju.git
- Add a new remote with the name
upstream
and set it to point to the upstreamjuju
repo.
git remote add upstream [email protected]:juju/juju.git
- Set your local branches to track the
upstream
remote (not your fork). E.g.,
git checkout 3.6
git branch --set-upstream-to=upstream/3.6
git checkout main
git branch --set-upstream-to=upstream/main
- Sync your local branches with the upstream, then check out the branch you
want to contribute to and create a feature branch based on it. If your
contribution is not specific to a particular branch, please target the lowest that
applies. (All patches in earlier versions are eventually merged through to later
versions.) E.g., for a change that should go into both Juju 3.6 and Juju 4
(
main
):
git fetch upstream
git checkout 3.6
git pull
git checkout -b 3.6-new-stuff # your feature branch
- Make the desired changes. Test changes locally.
Further info: Docs
The documentation is in juju/docs
, which is further split into user/
and
contributor/
. Some user reference docs (for the juju
CLI commands, the
controller and model configs, and the hook commands) are autogenerated from
source, and must be updated in source.
Tip: If you start from an existing doc on https://canonical-juju.readthedocs-hosted.com/en/latest/, you can find its source file by scrolling to the bottom of the page and clicking on Edit this page on GitHub -- though we still recommend you do not make changes there directly there but rather in a local clone, as that will make it easier for you to iterate during the PR review process.
All changes should follow the existing patterns, including Diátaxis, the Canonical Documentation Style Guide, the modular structure, the cross-referencing pattern, MyST Markdown, etc.
Changes should be inspected by building the docs and fixing any issues
discovered that way. To preview the docs as they will be rendered on RTD, in
juju/docs
run make run
and open the provided link in a browser. If you get
errors, try make clean
, then make run
again. For other checks, see make [Tab]
and select the command for the desired check.
Further info: Code
juju
is written in Go. To install Go see Go
docs.
Fork and clone the Juju repo, then navigate to the root directory and run make install
:
git clone https://github.com/<user>/juju.git
cd juju
make install
Juju uses Go modules to manage dependencies. To update a dependency, use the following, ensuring that the dependency is using a version where possible, or a commit hash if not available:
go get -u github.com/the/[email protected]
go mod tidy
To format your code, run go fmt
.
Note: Your editor may do this automatically.
Import statements are grouped into 3 sections: standard library, 3rd party libraries, juju imports. The tool "go fmt" can be used to ensure each group is alphabetically sorted. eg:
import (
"fmt"
"time"
"labix.org/v2/mgo"
"github.com/juju/loggo"
gc "gopkg.in/check.v1"
"github.com/juju/juju/state"
"github.com/juju/worker/v3"
)
Some tests may require local lxd to be installed, see installing lxd via snap.
Juju uses the gocheck
testing framework, which is automatically installed
as a dependency of juju
. You can read more about gocheck
at
http://godoc.org/gopkg.in/check.v1. gocheck
is integrated into the source of
each package so the standard go test
command is used to run gocheck
tests.
For example:
go test -v github.com/juju/juju/core/config -check.v
By default gocheck
will run all tests
in a package, selected tests can by run by passing -gocheck.f
to match a
subset of test names.
go test -gocheck.f '$REGEX'
Many tests use a standalone instance of mongod
as part of their setup. The
mongod
binary found in $PATH
is executed by these suites. If you don't
already have MongoDB installed, run
make install-mongo-dependencies
- As you make your changes, ensure that you always remain in sync with the upstream:
git pull upstream 3.6 --rebase
- Stage, commit and push regularly to your fork. Make sure your commit messages comply with conventional commits (see upstream standard, see adaptation in Juju). E.g.,
git add .
git commit -m "docs: add setup and teardown anchors"
git push origin 3.6-new-stuff
Note: For most code PRs, it's best to type just
git commit
, then return; the terminal will open a text editor, enabling you to write a lengthier, more explicit message.
Tip: If you've set things up correctly, typing just
git push
and returning may be enough forgit
to prompt you with the correct arguments.
Tip: If you don't want to create a new commit message every time, do
git commit --amend --no-edit
, thengit push --force
.
-
Create the PR. In the PR window make sure to select the correct target base branch. In your PR description make sure to comply with the template rules (e.g., explain why you're making the change). If your change should target multiple branches, add a note at the top of your PR to say so (e.g., "This PR should be merged into both
3.6
andmain
"). -
Ensure GitHub tests pass.
-
In the Matrix Juju Development channel, drop a link to your PR with the mention that it needs reviews. Someone will review your PR. Make all the requested changes.
-
When you've received two approvals, your PR can be merged. If you are part of the
juju
organization, at this point in the Conversation view of your PR you can type/merge
to merge. If not, ping one of your reviewers and ask them to help merge.
Tip: After your first contribution, you will only have to repeat steps 7-14.
Congratulations and thank you!