(contribute)=
A big welcome and thank you for considering contributing to Ubuntu Desktop Provision and Ubuntu! It’s people like you that make it a reality for users in our community.
Reading and following these guidelines will help us make the contribution process easy and effective for everyone involved. It also communicates that you agree to respect the time of the developers managing and developing this project. In return, we will reciprocate that respect by addressing your issue, assessing changes, and helping you finalise your pull requests.
These are mostly guidelines, not rules. Use your best judgement, and feel free to propose changes to this document in a pull request.
We take our community seriously and hold ourselves and other contributors to high standards of communication. By participating and contributing to this project, you agree to uphold our Code of Conduct.
PRs to our project are always welcome and can be a quick way to get your fix or improvement slated for the next release. In general, PRs should:
- Only fix/add the functionality in question OR address wide-spread empty space/style issues, not both.
- Add unit or integration tests for fixed or changed functionality.
- Address a single concern in the least number of changed lines as possible.
For changes that address core functionality or would require breaking changes (e.g. a major release), it's best to open an Issue to discuss your proposal first. This is not required but can save time creating and reviewing changes.
In general, we follow the "fork-and-pull" Git workflow
- Fork the repository to your own GitHub account
- Clone the project to your machine
- Create a branch locally with a succinct but descriptive name
- Commit changes to the branch
- Following any formatting and testing guidelines specific to this repo
- Push changes to your fork
- Open a PR in our repository and follow the PR template so that we can efficiently review the changes.
PRs will trigger unit and integration tests with and without race detection, linting and formatting validations, static and security checks, freshness of generated files verification. All the tests must pass before merging in main branch.
Please report any bugs related to Ubuntu Desktop Provision on Launchpad. We use the GitHub issue tracker only for issues related to the development of Ubuntu Desktop Provision itself.
Translations are managed using Weblate
Install Flutter - the currently used version is specified in .tool-versions. If you're using asdf to manage your Flutter SDK, you can simply run asdf install to install the required version.
Fetch Subiquity, which is included as a git sub-module, by running
git submodule update --init --recursive
and install its dependencies via
make install_deps
A Melos configuration is provided to make it straightforward to execute common tasks across all Dart/Flutter packages included in this project.
Install Melos:
dart pub global activate melos
Bootstrap the workspace:
melos bootstrap
Both ubuntu-desktop-bootstrap and ubuntu-desktop-init are built as snaps using source: . for their flutter-based UI. This works well in a pristine pipeline because there are no artefacts, but when running locally, host artefacts may taint the snapcraft builder. Let's walk through how to build locally and address these artefact:
git clone [email protected]:canonical/ubuntu-desktop-provision.git
cd ubuntu-desktop-provision
./ci/snap-build-setup.sh <bootstrap|init>
snapcraftIf you then make local edits, subsequent runs of snapcraft may fail. Individual situations may differ, but generally you can clear host artefacts and rebuild with:
flutter clean
snapcraft clean
rm -rf packages/subiquity_client/subiquity/.subiquity
rm -rf snap
./ci/snap-build-setup.sh <bootstrap|init>
snapcraftFinally, install the local build with sudo snap install <snap-artefact-name> --devmode.
The Dart/Flutter packages in this project use freezed and
json_serializable to generate
immutable data classes with JSON serialisation support.
Adding new types or members to classes annotated with @freezed or @JsonSerializable requires
the code to be re-generated.
Furthermore, mockito is used to generate mock classes for unit tests. If you modify the public API of existing classes that are mocked in tests or if you add new classes, you'll need to re-generate the mocks.
You can run the code generator from the working directory of a specific package with
dart run build_runner build --delete-conflicting-outputs
In order to re-generate the generated Dart code across all Dart/Flutter packages run:
melos generate
The project includes a comprehensive testsuite made of unit and integration tests. All the tests must pass before the review is considered. If you have troubles with the testsuite, feel free to mention it on your PR description.
You can run the unit tests for all Dart/Flutter packages in this project via
melos test
The test suite must pass before merging the PR to our main branch. Any new feature, change or fix must be covered by corresponding tests.
It is required to sign the Contributor License Agreement in order to contribute to this project.
An automated test is executed on PRs to check if it has been accepted.
This project is covered by THIS LICENSE.
Join us in the Ubuntu Community and post your question there with a descriptive tag.