From 3c08686571c5eeec0783cd07adc1e1227fc718ef Mon Sep 17 00:00:00 2001 From: Artem Konev Date: Fri, 6 Sep 2024 00:26:32 +0100 Subject: [PATCH 1/2] add contributing guide --- init.sh | 2 + sp-files/contributing.rst | 233 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 235 insertions(+) create mode 100644 sp-files/contributing.rst diff --git a/init.sh b/init.sh index dd7926b2..c64842d0 100755 --- a/init.sh +++ b/init.sh @@ -33,6 +33,8 @@ sed -i "s|working-directory:\s*'\.'|working-directory: '$install_directory'|g" " echo "Updating .readthedocs.yaml configuration..." sed -i "s|configuration:\s*sp-docs/conf\.py|configuration: $install_directory/conf.py|g" "$temp_directory/sp-files/.readthedocs.yaml" sed -i "s|requirements:\s*sp-docs/\.sphinx/requirements\.txt|requirements: $install_directory/.sphinx/requirements.txt|g" "$temp_directory/sp-files/.readthedocs.yaml" +echo "Updating contribution guide..." +sed -i "s|DOCDIR|$install_directory|g" "$temp_directory/sp-files/contributing.rst" # Update the GitHub folder path in the configuration file echo "Updating conf.py configuration..." diff --git a/sp-files/contributing.rst b/sp-files/contributing.rst new file mode 100644 index 00000000..5393fc0a --- /dev/null +++ b/sp-files/contributing.rst @@ -0,0 +1,233 @@ +.. 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 + +How to contribute +================= + +We believe that everyone has something valuable to contribute, +whether you're a coder, a writer or a tester. +Here's how and why you can get involved: + +- **Why join us?** Work with like-minded people, develop your skills, + connect with diverse professionals, and make a difference. + +- **What do you get?** Personal growth, recognition for your contributions, + early access to new features and the joy of seeing your work appreciated. + +- **Start early, start easy**: Dive into code contributions, + improve documentation, or be among the first testers. + Your presence matters, + regardless of experience or the size of your contribution. + + +The guidelines below will help keep your contributions effective and meaningful. + + +Code of conduct +--------------- + +When contributing, you must abide by the +`Ubuntu Code of Conduct `_. + + +Licence and copyright +--------------------- + +By default, all contributions to ACME are made under the AGPLv3 licence. +See the `licence `_ +in the ACME GitHub repository for details. + +All contributors must sign the `Canonical contributor licence agreement +`_, +which grants Canonical permission to use the contributions. +The author of a change remains the copyright owner of their code +(no copyright assignment occurs). + + +Pull requests +------------- + +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 +~~~~~~~~~~~~~~ + +.. TODO: Update with your template checklist details or drop if excessive + +- **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. + +- **Relevant issues**: Reference any + `related issues, PRs and repos `_. + +- **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. + + +Commits +~~~~~~~ + +Use separate commits for each logical change, +and for changes to different components. +Prefix your commits with the component they affect, +using the code tree structure, +e.g. prefix a commit that updates the ACME service with ``acme/service:``. + +Use `conventional commits `_ +for your commit messages 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 + + * Ensure the source directory is owned by the user running a container. + + Links: + - ... + - ... + + +Such structure makes it easier to review contributions +and simplifies porting fixes to other branches. + + +Developer certificate of origin +------------------------------- + +.. TODO: Update with your details or drop if excessive + +To improve contribution tracking, +we use the `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 +certifying that you wrote it +or have the right to commit it as an open-source contribution. + +To sign off on a commit, use the ``--signoff`` option in ``git commit``. + + +Code +---- + +.. TODO: Update with your details; these are reasonable defaults + +The formatting rules for ACME are enforced automatically using +`flake8 `_ +and `Black `_. + +To run the checks locally before submitting your changes: + +.. code-block:: console + + make format + + +Code structure +~~~~~~~~~~~~~~ + +- **Check linked code elements**: + Check that coupled code elements, files and directories are adjacent. + For instance, store test data close to the corresponding test code. + +- **Group variable declaration and initialisation**: + Declare and initialise variables together + to improve code organisation and readability. + +- **Split large expressions**: + Break down large expressions + into smaller self-explanatory parts. + Use multiple variables where appropriate + to make the code more understandable + and choose names that reflect their purpose. + +- **Use blank lines for logical separation**: + 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. + +- **Remove dead code and redundant comments**: + Drop unused or obsolete code and comments. + This promotes a cleaner code base and reduces confusion. + +- **Normalise symmetries**: + Treat identical operations consistently, using a uniform approach. + This also improves consistency and readability. + + +Tests +----- + +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 + + +Documentation +------------- + +ACME's documentation is stored in the ``DOCDIR`` directory of the repository. +It is based on the `Canonical starter pack +`_ +and hosted on `Read the Docs `_. + +For general guidance, +refer to the `starter pack guide +`_. + +For syntax help and guidelines, +refer to the `Canonical style guides +`_. + +In structuring, +the documentation employs the `Diátaxis `_ approach. + +To run the documentation locally before submitting your changes: + +.. code-block:: console + + make run + + +Automatic checks +~~~~~~~~~~~~~~~~ + +GitHub runs automatic checks on the documentation +to verify spelling, validate links and suggest inclusive language. + +You can (and should) run the same checks locally: + +.. code-block:: console + + make spelling + make linkcheck + make woke From 475f9a2e5a3a3c86c15a92dac71d3af4e2f6e695 Mon Sep 17 00:00:00 2001 From: Artem Konev Date: Tue, 17 Sep 2024 10:23:47 +0100 Subject: [PATCH 2/2] add review comments --- sp-files/contributing.rst | 147 +++++++++++++++++++++++++++----------- sp-files/index.rst | 1 + 2 files changed, 105 insertions(+), 43 deletions(-) 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