Skip to content

Latest commit

 

History

History
284 lines (200 loc) · 8.64 KB

CONTRIBUTING.md

File metadata and controls

284 lines (200 loc) · 8.64 KB

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.

Open an issue

You will need a GitHub account (sign up).

Open an issue for docs

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.

Open an issue for code

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

Make your first contribution

You will need a GitHub account (sign up and add your public SSH key) and git (get started).

Then:

  1. Sign the Canonical Contributor Licence Agreement (CLA).

  2. 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

See more: GitHub | Authentication > Signing commits

  1. Fork juju/juju. This will create https://github.com/<user>/juju.

  2. Clone your fork locally.

git clone [email protected]:<user>/juju.git
  1. Add a new remote with the name upstream and set it to point to the upstream juju repo.
git remote add upstream [email protected]:juju/juju.git
  1. 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
  1. 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
  1. 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.

Standards

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.

Testing

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

Installing Go

juju is written in Go. To install Go see Go docs.

Building Juju and its dependencies

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

Updating Go dependencies

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

Code formatting

To format your code, run go fmt.

Note: Your editor may do this automatically.

Imports

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"
    )

Testing

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'

Testing and MongoDB

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
  1. As you make your changes, ensure that you always remain in sync with the upstream:
git pull upstream 3.6 --rebase
  1. 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 for git 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, then git push --force.

  1. 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 and main").

  2. Ensure GitHub tests pass.

  3. 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.

  4. 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!