diff --git a/sp-files/contributing.rst b/sp-files/contributing.rst index 5393fc0a..ded2f98a 100644 --- a/sp-files/contributing.rst +++ b/sp-files/contributing.rst @@ -1,7 +1,6 @@ .. TODO: Replace all mentions of ACME with your project name -.. TODO: Adjust all URLs (GitHub, etc.) accordingly -.. TODO: Adjust the guide as needed -.. TODO: Address all other TODOs below +.. TODO: Update all sections containing TODOs; make sure no TODOs are left + How to contribute ================= @@ -35,8 +34,10 @@ When contributing, you must abide by the Licence and copyright --------------------- +.. TODO: Update with your license details or drop if excessive + By default, all contributions to ACME are made under the AGPLv3 licence. -See the `licence `_ +See the `licence `_ in the ACME GitHub repository for details. All contributors must sign the `Canonical contributor licence agreement @@ -46,56 +47,106 @@ The author of a change remains the copyright owner of their code (no copyright assignment occurs). -Pull requests -------------- +Releases and versions +--------------------- + +.. TODO: Add your release and versioning details or drop if excessive + +ACME uses `semantic versioning `_; +major releases occur once or twice a year. + +The release notes can be found `TODO: here `_. + + +Environment setup +----------------- + +.. TODO: Update with your prerequisites or drop if excessive + +To work on the project, you need the following prerequisites: + +- `TODO: Prerequisite 1 `_ +- `TODO: Prerequisite 2 `_ + + +To install and configure these tools: + +.. code-block:: console + + TODO: prerequisite command 1 + TODO: prerequisite command 2 + + +Submitting changes +------------------ + +.. TODO: Suggest your own PR process or drop if excessive + +If you want to address an issue or a bug in ACME, +notify in advance the people involved to avoid confusion; +also, reference the issue or bug number when you submit the changes. + +- `Fork + `_ + our `GitHub repository `_ + and add the changes to your fork, + properly structuring your commits, + providing detailed commit messages + and signing your commits. + +- Make sure the updated project builds and runs without warnings or errors; + this includes linting, documentation, code and tests. + +- Submit the changes as a `pull request (PR) + `_. -Submit your changes as pull requests on `GitHub -`_. -Before you open a pull request, -ensure that the build occurs without any warnings or errors; -this includes documentation and tests. Your changes will be reviewed in due time; if approved, they will be eventually merged. -PR description -~~~~~~~~~~~~~~ +Describing pull requests +~~~~~~~~~~~~~~~~~~~~~~~~ -.. TODO: Update with your template checklist details or drop if excessive +.. TODO: Update with your own checklist or drop if excessive + +To be properly considered, reviewed and merged, +your pull request must provide the following details: - **Title**: Summarise the change in a short, descriptive title. -- **Description**: Provide an explanation of the problem your PR addresses. - Highlight any new features, bug fixes or refactoring. +- **Description**: Explain the problem that your pull request solves. + Mention any new features, bug fixes or refactoring. - **Relevant issues**: Reference any - `related issues, PRs and repos `_. + `related issues, pull requests and repositories `_. - **Testing**: Explain whether new or updated tests are included. - **Reversibility**: If you propose decisions that may be costly to reverse, - outline the reasons and provide the steps to reverse if necessary. + list the reasons and suggest steps to reverse the changes if necessary. + +Commit structure and messages +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Commits -~~~~~~~ +.. TODO: Update with your own guidelines or drop if excessive Use separate commits for each logical change, and for changes to different components. -Prefix your commits with the component they affect, +Prefix your commit messages with names of components they affect, using the code tree structure, -e.g. prefix a commit that updates the ACME service with ``acme/service:``. +e.g. start a commit that updates the ACME service with ``ACME/service:``. Use `conventional commits `_ -for your commit messages to ensure consistency across the project: +to ensure consistency across the project: .. code-block:: none Ensure correct permissions and ownership for the content mounts * Work around an ACME issue regarding empty dirs: - https://github.com/canonical/acme/issues/12345 + https://github.com/canonical/ACME/issues/12345 * Ensure the source directory is owned by the user running a container. @@ -108,13 +159,14 @@ Such structure makes it easier to review contributions and simplifies porting fixes to other branches. -Developer certificate of origin -------------------------------- +Signing commits +~~~~~~~~~~~~~~~ -.. TODO: Update with your details or drop if excessive +.. TODO: Update with your suggestions or drop if excessive To improve contribution tracking, -we use the `DCO 1.1 `_ +we use the developer certificate of origin +(`DCO 1.1 `_) and require a "sign-off" for any changes going into each branch. The sign-off is a simple line at the end of the commit message @@ -127,21 +179,27 @@ To sign off on a commit, use the ``--signoff`` option in ``git commit``. Code ---- -.. TODO: Update with your details; these are reasonable defaults +Formatting and linting +~~~~~~~~~~~~~~~~~~~~~~ + +.. TODO: Update with your linting configuration setup or drop if excessive + +ACME relies on these formatting and linting tools: + +- `TODO: Tool 1 `_ +- `TODO: Tool 2 `_ -The formatting rules for ACME are enforced automatically using -`flake8 `_ -and `Black `_. -To run the checks locally before submitting your changes: +To configure and run them: .. code-block:: console - make format + TODO: lint command 1 + TODO: lint command 2 -Code structure -~~~~~~~~~~~~~~ +Structure +~~~~~~~~~ - **Check linked code elements**: Check that coupled code elements, files and directories are adjacent. @@ -162,10 +220,6 @@ Code structure Insert a blank line between two logically separate sections of code. This improves its structure and makes it easier to understand. - -Coding standards -~~~~~~~~~~~~~~~~ - - **Avoid nested conditions**: Avoid nesting conditions to improve readability and maintainability. @@ -178,18 +232,25 @@ Coding standards This also improves consistency and readability. +Best practices +~~~~~~~~~~~~~~ + +.. TODO: Update with your best practices or drop if excessive + + Tests ----- +.. TODO: Update with your testing framework details or drop if excessive + All code contributions must include tests. To run the tests locally before submitting your changes: -.. TODO: Update with your details - .. code-block:: console - make test + TODO: test command 1 + TODO: test command 2 Documentation diff --git a/sp-files/index.rst b/sp-files/index.rst index 6563baf2..acf439f0 100644 --- a/sp-files/index.rst +++ b/sp-files/index.rst @@ -66,3 +66,4 @@ Example Project is a member of the Ubuntu family. It’s an open source project :maxdepth: 2 self + contributing