Hello everyone,
This is a hands-on, beginner-friendly session designed to help you make your first open source contribution through documentation - from picking an issue to getting your PR merged.
What’s the workshop about?
We’ll be working with real open issues from the CODA repository, so you will:
-
Understand the full contribution process from issue selection to PR merging
-
Learn how to engage with the CODA community and request assignments
-
Get comfortable with the mentorship workflow we use for contributors
-
Navigate practical steps like signing the Canonical Contributor License (CLA) and understanding review feedback
By the end of the workshop, you will have:
-
Made your first CODA contribution (in review or merged).
-
A clear roadmap to keep contributing after DjangoCon
Who is this for?
- Anyone curious about starting in open source but unsure how to begin
- Developers, writers, and community members who want to make meaningful contributions through CODA and similar projects
Preparing for the workshop
Due to the limited time available for the workshop, take some time to set yourself up for success.
Sign up and set up GitHub (If you don’t already have an account)
Most Canonical documentation is hosted and maintained on GitHub. You’ll need an account to review the tasks on the CODA repository and contribute to different projects’ documentation.
You’ll also need the email address associated with your GitHub account when signing the CLA. Follow this link to open a GitHub account if you don’t already have one, and set up Git this way.
Sign the Contributor License Agreement
All contributors to a Canonical open-source project are required to sign the contributor license agreement (CLA). To get instant access, sign the CLA as an individual contributor. You will need a GitHub or Launchpad account to complete this step.
Set up Linux/Ubuntu environments
To ensure we start right away, please come with a working Ubuntu environment:
-
Ubuntu users: See next steps.
-
Windows users: We recommend installing Multipass and launching an Ubuntu VM
- You can also use WSL with Ubuntu, but Multipass provides a smoother setup for this workshop
-
MacOS users: Please install Multipass and create an Ubuntu VM
We may not have time to do these installations during the session, so please prepare your environment beforehand.
Git, Make, Python-venv
- Open terminal (CTRL+ALT+T) and install git:
sudo apt install git
- Set your commit email with the command below without the quotes. Email should be the same one used to sign up to GitHub:
git config --global user.email "YOUR_EMAIL"
- The Make command is used to build the documentation on your local machine. To use this command, you must install the associated tool:
sudo apt install make
- Local builds of the documentation are run inside a virtual environment. The starter pack uses Python’s
venvmodule to create these environments. Install this module:
sudo apt install python3.12-venv
Optional step
When you try to build the documentation locally for the first time, the make install or make run commands will result in multiple dependencies being downloaded. This only happens the first time you build sphinx-based documentation or when you switch to a different version of the Canonical documentation starter pack. The download process may take a long time without a stable internet connection.
To mitigate this, you can fork a suitable sphinx-based documentation project, e.g., the starter-pack, open your terminal and navigate to the folder as Makefile, then execute make install. For example:
hostname:~/Documents/launchpad-manual/docs$ make run
Once the relevant dependencies are installed the first time round, they won’t have to be installed again for the same or another sphinx-based documentation project.
See you there
Bring your curiosity, your questions, and your Ubuntu-ready machine and let’s make your first open source contribution together!