Contributing changes¶

This guide shows you how to contribute a change to Launchpad.

Discuss the change¶

To begin with, it is usually helpful to discuss the change you’d like to make, in a bug or directly with the Launchpad team.

Fork the Launchpad repository¶

Navigate to the Launchpad project page and go to the “Code” tab. https://code.launchpad.net/launchpad

Click “Fork it to your account” to create a copy of the project in your Launchpad account.

Assuming you have added your SSH keys to launchpad, you can then clone your fork of the repository:

git clone git+ssh://~<your-username>@git.launchpad.net/~<your-username>/launchpad
cd launchpad

Add the Launchpad repository as a remote¶

This will be useful to pull in changes from the main Launchpad repository.

git remote add launchpad git+ssh://git.launchpad.net/launchpad

Make your changes¶

Create a branch from a reasonable point, such as master.

git checkout -b <descriptive-branch-name>

Make your changes on the branch. Be sure to test them locally by setting up a local Launchpad development instance.

Make sure you add or update existing unit tests for your changes.

When it comes to commit messages, please follow these guidelines:

The title should be short, but descriptive.
The title should use imperative wording, e.g. “Add character limit to bug title’s summary field”.
The title should always start with a capitalized word and should not end with a full stop.
If required, give more context about the motivation of the change in the commit body.
Any line length should not exceed 72 characters for better readability, except for hyperlinks.
Where relevant, it should contain a reference to a Launchpad bug, e.g. LP: #2086655.

Run the unit tests¶

To run the complete test suite (which may take hours depending on your machine), run the following command from the top of the Launchpad repository:

xvfb-run bin/test -vvc

To run specific tests, you can use the -t option to specify test patterns or files. For example:

bin/test -vvc -t test-pattern-1 -t dotted.path.to.file

Run the pre-commit hook¶

If you followed the instructions to set up and run Launchpad, you should already have pre-commit installed and have the pre-commit git hook installed. If not, complete these steps before proceeding.

Push your changes¶

Once you are happy with your changes, stage and commit them, and then push to your fork.

Create a merge proposal¶

Once your commit has been pushed to a personal git repository, you can follow the direct link in the post-push message to create a merge proposal. Alternatively, in a web browser, visit

https://code.launchpad.net/~<username>/+git

Remember to replace your username in the URL.

Navigate to the personal repository to which you pushed your changes, and then to the branch containing your commit.

Select Propose for merging, provide a reasonable commit message, and description of your changes.

What comes next?¶

Once you have created a merge proposal, a Launchpad maintainer will inspect your merge proposal and approve or reject the changes. There may be comments that require you to make amendments to your proposed changes, which you can do by repeating this workflow. However, once your changes are approved, your changes will be merged into the master branch of the Launchpad code base!

Once your changes are merged into the master branch, they get deployed to the QA staging site automatically. You can QA your changes there: https://qastaging.launchpad.net/