This document describes how to contribute changes to
It assumes you have a GitHub account, and refers to your GitHub user
Submitting your first pull request#
Before any pull request can be accepted, you must do the following:
Sign the Canonical contributor license agreement.
Add your GitHub username (alphabetically) to the in-repository list that we use to track CLA signatures: tools/.github-cla-signers.
Add or update any unit tests accordingly.
Add or update any Integration testing (if applicable).
Format code (using
isort) with tox -e do_format.
Ensure unit tests and linting pass using tox.
Submit a PR against the
mainbranch of the
The detailed instructions#
Follow these steps to submit your first pull request to
To contribute to
cloud-init, you must sign the Canonical contributor license agreement.
If you have already signed it as an individual, your Launchpad user will be listed in the contributor-agreement-canonical group. Unfortunately there is no easy way to check if an organization or company you are doing work for has signed.
When signing it:
ensure that you fill in the GitHub username field,
when prompted for ‘Project contact’ or ‘Canonical Project Manager’, enter ‘James Falcon’.
If your company has signed the CLA for you, please contact us to help in verifying which Launchpad/GitHub accounts are associated with the company.
For any questions or help with the process, please email James Falcon with the subject, “Cloud-init CLA”.
You also may contact user
#cloud-initchannel on the Libera IRC network.
gitwith your email and name for commit messages.
Your name will appear in commit messages and will also be used in changelogs or release notes. Give yourself credit!
git config user.name "Your Name" git config user.email "Your Email"
Sign in to your GitHub account.
Fork the upstream repository on GitHub and click on the
Create a new remote pointing to your personal GitHub repository.
git clone email@example.com:GH_USER/cloud-init.git cd cloud-init git remote add upstream firstname.lastname@example.org:canonical/cloud-init.git git push origin main
Read through the
cloud-initCode Review Process, so you understand how your changes will end up in
Submit your first
cloud-initpull request, adding your GitHub username to the in-repository list that we use to track CLA signatures: tools/.github-cla-signers
See PR #344 and PR #345 for examples of what this pull request should look like.
.github-cla-signersis sorted alphabetically.
You may use
.github-cla-signersor check that it is sorted.
If you already have a change that you want to submit, you can also include the change to
tools/.github-cla-signersin that pull request, there is no need for two separate PRs.
Transferring CLA Signatures from Launchpad to GitHub#
For existing contributors who signed the agreement in Launchpad before the
GitHub username field was included, we need to verify the link between your
Launchpad account and your GitHub account. To enable us to do this, we
ask that you create a branch with both your Launchpad and GitHub usernames
against both the Launchpad and GitHub
cloud-init repositories. We’ve added
a tool (
tools/migrate-lp-user-to-github) to the
to handle this migration as automatically as possible.
cloud-init team will review the two merge proposals, verify that the
CLA has been signed for the Launchpad user, and record the associated GitHub
If you are a first time contributor, you will not need to touch
Launchpad to contribute to
cloud-init. All new CLA signatures are
handled as part of the GitHub pull request process described above.
Do these things for each feature or bug#
Create a new topic branch for your work:
git checkout -b my-topic-branch
Make and commit your changes (note, you can make multiple commits, fixes, and add more commits.):
isortformatting rules with tox:
tox -e do_format
Run unit tests and lint/formatting checks with tox:
Push your changes to your personal GitHub repository:
git push -u origin my-topic-branch
Use your browser to create a pull request:
Open the branch on GitHub
You can see a web view of your repository and navigate to the branch at:
Click Pull Request.
Fill out the pull request title, summarizing the change and a longer message indicating important details about the changes included, like:
Activate the frobnicator. The frobnicator was previously inactive and now runs by default. This may save the world some day. Then, list the bugs you fixed as footers with syntax as shown here. The commit message should be one summary line of less than 70 characters followed by a blank line, and then one or more paragraphs wrapped at 72 characters describing the change and why it was needed. This is the message that will be used on the commit when it is squashed and merged into main. If there is a related launchpad bug, specify it at the bottom of the commit message. LP: #NNNNNNN (replace with the appropriate bug reference or remove this line entirely if there is no associated bug)
Note that the project continues to use LP: #NNNNN format for closing launchpad bugs rather than GitHub Issues.
Click Create Pull Request
cloud-init committer will review your changes and
follow up in the pull request. Look at the Code Review Process documentation to understand the following steps.
Feel free to ping and/or join
#cloud-init on Libera IRC if you
have any questions.
This section captures design decisions that are helpful to know when
Cloud-init upstream currently supports Python 3.6 and above.
Cloud-init upstream will stay compatible with a particular Python version
for 6 years after release. After 6 years, we will stop testing upstream
changes against the unsupported version of Python and may introduce
breaking changes. This policy may change as needed.
The following table lists the
cloud-init versions in which the
minimum Python version changed:
Cloud Config Modules#
Any new modules should use underscores in any new config options and not hyphens (e.g. new_option and not new-option).
cloud-init must include testing. See Testing for
details on these requirements.
cloud-init codebase uses Python’s annotation support for storing
type annotations in the style specified by PEP-484 and PEP-526.
Their use in the codebase is encouraged.
Feature flags are used as a way to easily toggle configuration at build time. They are provided to accommodate feature deprecation and downstream configuration changes.
Currently used upstream values for feature flags are set in
cloudinit/features.py. Overrides to these values (typically via quilt
patch) can be placed
in a file called
feature_overrides.py in the same directory. Any value
feature_overrides.py will override the original value set
Each flag should include a short comment regarding the reason for the flag and intended lifetime.
Tests are required for new feature flags, and tests must verify all valid states of a flag, not just the default state.
- cloudinit.features.ALLOW_EC2_MIRRORS_ON_NON_AWS_INSTANCE_TYPES = False#
When configuring apt mirrors, if
Truecloud-init will detect that a datasource’s
availability_zoneproperty looks like an EC2 availability zone and set the
ec2_regionvariable when generating mirror URLs; this can lead to incorrect mirrors being configured in clouds whose AZs follow EC2’s naming pattern.
As of 20.3,
Falseso we no longer include
ec2_regionin mirror determination on non-AWS cloud platforms.
If the old behavior is desired, users can provide the appropriate mirrors via
apt:directives in cloud-config.
- cloudinit.features.ERROR_ON_USER_DATA_FAILURE = True#
If there is a failure in obtaining user data (i.e., #include or decompress fails) and
False, cloud-init will log a warning and proceed. If it is
True, cloud-init will instead raise an exception.
As of 20.3,
(This flag can be removed after Focal is no longer supported.)
- cloudinit.features.EXPIRE_APPLIES_TO_HASHED_USERS = True#
EXPIRE_APPLIES_TO_HASHED_USERSis True, then when expire is set true in cc_set_passwords, hashed passwords will be expired. Previous to 22.3, only non-hashed passwords were expired.
(This flag can be removed after Jammy is no longer supported.)
- cloudinit.features.NETPLAN_CONFIG_ROOT_READ_ONLY = True#
NETPLAN_CONFIG_ROOT_READ_ONLYis True, then netplan configuration will be written as a single root readon-only file /etc/netplan/50-cloud-init.yaml. This prevents wifi passwords in network v2 configuration from being world-readable. Prior to 23.1, netplan configuration is world-readable.
(This flag can be removed after Jammy is no longer supported.)
- cloudinit.features.NOCLOUD_SEED_URL_APPEND_FORWARD_SLASH = True#
Append a forward slash ‘/’ if NoCloud seedurl does not end with either a querystring or forward slash. Prior to 23.1, nocloud seedurl would be used unaltered, appending meta-data, user-data and vendor-data to without URL path separators.
(This flag can be removed when Jammy is no longer supported.)