From bbb08b426f80bbd9f6630b373eda3e4e682be1ac Mon Sep 17 00:00:00 2001 From: James Falcon Date: Mon, 2 Oct 2023 17:04:50 -0500 Subject: [PATCH] apply my comments --- doc/rtd/development/code_review.rst | 21 +--- doc/rtd/development/contribute_docs.rst | 4 +- doc/rtd/development/dir_layout.rst | 30 ------ doc/rtd/development/docs_layout.rst | 6 ++ doc/rtd/development/find_issues.rst | 16 ++- doc/rtd/development/first_PR.rst | 128 ++++-------------------- doc/rtd/development/index.rst | 28 +----- doc/rtd/development/style_docs.rst | 2 +- doc/rtd/links.txt | 2 + 9 files changed, 44 insertions(+), 193 deletions(-) diff --git a/doc/rtd/development/code_review.rst b/doc/rtd/development/code_review.rst index db6c719ddb8b..df8d692b88fb 100644 --- a/doc/rtd/development/code_review.rst +++ b/doc/rtd/development/code_review.rst @@ -25,8 +25,9 @@ Cloud-init contributors, community members and users are encouraged to ask for help if they need it. If you have questions about the code review process, or need advice on an open PR, these are the available avenues: -* on an open PR, leave a comment on that PR, +* Open a PR, add "WIP:" to the title, and leave a comment on that PR * join the ``#cloud-init`` `channel on the Libera IRC `_ network +* post on the ``#cloud-init`` `Discourse topic `_ * send an email to the cloud-init mailing list: :: cloud-init@lists.launchpad.net @@ -132,30 +133,16 @@ There are three potential outcomes: **merged**, **rejected permanently**, and the :ref:`inactive pull requests` section for details about temporary closure. -In this section, we use the verbs "merge" or "squash merge" to mean "squash -merged using the GitHub UI", which is the only way that changes can land in -cloud-init's ``main`` branch. - A committer is assigned ----------------------- -The committers, as a team, assign a committer to the PR. This committer is +The committers assign a committer to the PR. This committer is expected to shepherd the PR to completion (and to merge it, if that is the outcome reached). They perform an initial review, and monitor the PR to ensure the proposer is receiving help if they need it. The committers perform this assignment on a -daily basis for any new PRs submitted. - -This assignment gives the proposer a clear point of contact with a cloud-init -core developer, and ensures that they get timely feedback on their PR. It does -not imply that the committer has ownership over the review process, or that -they are the only person who can review the PR. Any other reviewers should feel -free to add their comments and suggestions as they wish. - -The assigned committer can delegate the code review of a PR to another reviewer -if they think that person would be better suited. In GitHub terms, this is -setting an **Assignee**, not requesting a review. +regular basis for any new PRs submitted. Committer's initial review -------------------------- diff --git a/doc/rtd/development/contribute_docs.rst b/doc/rtd/development/contribute_docs.rst index c5a0b1701041..6ba12179cdd0 100644 --- a/doc/rtd/development/contribute_docs.rst +++ b/doc/rtd/development/contribute_docs.rst @@ -55,8 +55,8 @@ You will need to add your GitHub username (alphabetically) to the in-repository list that we use to track :ref:`CLA signatures `: `tools/.github-cla-signers`_. -This needs to be included alongside your first contribution: we cannot merge a -PR that only adds your name to the CLA. +Please include this in the same PR alongside your first contribution. Do +not create a separate PR to add your name to the CLA signatures. If you need some help with your contribution, you can contact us on our `IRC channel `_. If you have already submitted a work-in-progress PR, you diff --git a/doc/rtd/development/dir_layout.rst b/doc/rtd/development/dir_layout.rst index 7b56a49525a2..4b0a0e2eddbe 100644 --- a/doc/rtd/development/dir_layout.rst +++ b/doc/rtd/development/dir_layout.rst @@ -3,36 +3,6 @@ Directory layout **************** -Cloud-init's directory structure is somewhat different from a regular -application: :: - - /var/lib/cloud/ - - data/ - - instance-id - - previous-instance-id - - datasource - - previous-datasource - - previous-hostname - - handlers/ - - instance - - instances/ - i-00000XYZ/ - - boot-finished - - cloud-config.txt - - datasource - - handlers/ - - obj.pkl - - scripts/ - - sem/ - - user-data.txt - - user-data.txt.i - - scripts/ - - per-boot/ - - per-instance/ - - per-once/ - - seed/ - - sem/ - ``/var/lib/cloud`` ================== diff --git a/doc/rtd/development/docs_layout.rst b/doc/rtd/development/docs_layout.rst index 2dc390a4b6b5..0f981a2afeb1 100644 --- a/doc/rtd/development/docs_layout.rst +++ b/doc/rtd/development/docs_layout.rst @@ -36,6 +36,9 @@ directory: ``man/`` ======== +This subdirectory contains the Linux man pages for the binaries provided +by cloud-init. + ``rtd/`` ======== @@ -68,6 +71,9 @@ can be found in this folder. ``sources/`` ============ +This subdirectory contains demos which can help the reader understand +how parts of the product work. + .. LINKS .. include:: ../links.txt diff --git a/doc/rtd/development/find_issues.rst b/doc/rtd/development/find_issues.rst index 3fb370de78fc..8572ece36c33 100644 --- a/doc/rtd/development/find_issues.rst +++ b/doc/rtd/development/find_issues.rst @@ -18,26 +18,24 @@ Claiming an issue You can express your interest in an issue by posting a comment on it. You should only work on one open issue at a time to avoid overloading yourself. -If you have not submitted a PR (or a draft/"work-in-progress" PR) within a few -days of leaving your comment, other contributors should consider the issue to -be available for them to work on. +If you have not submitted a PR or commented with an updated status within a +week of leaving your initial comment, other contributors should consider the +issue to be available for them to work on. When you submit your proposed fix for an issue, including the issue number in the PR commit message will link the issue to your proposed fix. This is the ``Fixes GH-0000`` line in the template PR commit message. -We will only assign an issue if there is a PR in progress. - Creating an issue ================= If you've spotted something that doesn't already have an issue, you can always create one in GitHub. -You can also submit an issue in GitHub through the documentation using the -"Give feedback" button at the top of each page. It will automatically include -the URL of the page you came from, so all you need to do is describe the issue -you've found. +For documentation issues, you can submit an issue in GitHub using the +"Give feedback" button at the top of each documentation page. It will +automatically include the URL of the page you came from, so all you need to +do is describe the issue you've found. No-code or low-code options =========================== diff --git a/doc/rtd/development/first_PR.rst b/doc/rtd/development/first_PR.rst index c5f90e41706d..b76028d56ef8 100644 --- a/doc/rtd/development/first_PR.rst +++ b/doc/rtd/development/first_PR.rst @@ -1,7 +1,14 @@ Submit your first pull request ****************************** -Follow these steps to submit your first pull request to cloud-init: +Follow these steps prior to submitting your first pull request to cloud-init: + +Setup Git and GitHub appropriately +================================== + +Understanding how to use Git and GitHub is a prerequisite for contributing to +cloud-init. Please refer to the `GitHub quickstart`_ documentation +for more information. Sign the CLA ============ @@ -28,131 +35,38 @@ For any questions or help with the process, email "Cloud-init CLA". You can also contact user ``falcojr`` in the #cloud-init channel on the `Libera IRC network `_. -Configure git -============= - -Next, configure ``git`` with 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" - -Clone the repository -==================== - -* Sign in to your `GitHub`_ account. - -* From the cloud-init `upstream repository `_ on GitHub, click on the - :guilabel:`Fork` button. - -* Create a new remote pointing to your personal GitHub repository. - - .. code-block:: sh - - git clone git@github.com:GH_USER/cloud-init.git - cd cloud-init - git remote add upstream git@github.com:canonical/cloud-init.git - git push origin main - - Remember to change ``GH_USER`` to your GitHub username. - -Work on your feature or bug -=========================== +Add your name to the CLA signers list +===================================== -Create a new topic branch for your work: :: +As part of your first PR to cloud-init, you should also add your GitHub +username (alphabetically) to the in-repository list that we use to track CLA +signatures: `tools/.github-cla-signers`_. - git checkout -b my-topic-branch +`PR #344`_ and `PR #345`_ are good examples of what this should look like in +your pull request, though please do not use a separate PR for this step. -Create a virtual environment ----------------------------- +Create a sandbox environment +============================ It is very often helpful to create a safe and sandboxed environment to test your changes in while you work. If you are not sure how to do this, check out :ref:`our QEMU tutorial`, which walks through this process step-by-step. -Make your commits ------------------ - -Make and commit your changes (note, you can make multiple commits, fixes, and -add more commits): :: - - git commit - -Add your name to the CLA signers list -------------------------------------- - -As part of your first PR to cloud-init, you should also add your GitHub -username (alphabetically) to the in-repository list that we use to track CLA -signatures: `tools/.github-cla-signers`_. - -`PR #344`_ and `PR #345`_ are good examples of what this should look like in -your pull request. - Format the code ---------------- +=============== Apply the ``black`` and ``isort`` formatting rules with `tox`_: :: tox -e do_format Run unit tests --------------- +============== Run unit tests and lint/formatting checks with `tox`_: :: tox -Push your changes ------------------ - -Push your changes to your personal GitHub repository: :: - - git push -u origin my-topic-branch - -Create a pull request -===================== - -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: :: - - https://github.com/GH_USER/cloud-init/tree/my-topic-branch - -- Click :guilabel:`Pull Request`. - -- Fill out the pull request title, summarizing the change and a longer message - indicating important details about the changes included, like: - - .. code-block:: text - - 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 Launchpad bug) - Fixes GH-00000 (replace with the appropriate GitHub issue number or remove this line if there's no associated GitHub issue) - - Note that the project continues to use LP: #NNNNN format for closing - Launchpad bugs rather than GitHub Issues. - -- Click :guilabel:`Create Pull Request` - Read our code review process ============================ @@ -161,11 +75,7 @@ cloud-init :ref:`Code Review Process`, so you can understand how your changes will end up in cloud-init's codebase. .. include:: ../links.txt -.. _quickstart documentation: https://docs.github.com/en/get-started/quickstart .. _tools/.github-cla-signers: https://github.com/canonical/cloud-init/blob/main/tools/.github-cla-signers -.. _repository: https://github.com/canonical/cloud-init .. _contributor-agreement-canonical: https://launchpad.net/%7Econtributor-agreement-canonical/+members .. _PR #344: https://github.com/canonical/cloud-init/pull/344 .. _PR #345: https://github.com/canonical/cloud-init/pull/345 -.. _PEP-484: https://www.python.org/dev/peps/pep-0484/ -.. _PEP-526: https://www.python.org/dev/peps/pep-0526/ diff --git a/doc/rtd/development/index.rst b/doc/rtd/development/index.rst index 7021aa602467..70a593e697ba 100644 --- a/doc/rtd/development/index.rst +++ b/doc/rtd/development/index.rst @@ -49,8 +49,8 @@ Getting started first_PR.rst code_review.rst -For existing contributors -========================= +Contribute +========== Pull request checklist ---------------------- @@ -62,7 +62,7 @@ Before any pull request can be accepted, remember to do the following: * Add or update any :ref:`unit tests` accordingly. * Add or update any :ref:`integration_tests` (if applicable). * Format code (using ``black`` and ``isort``) with ``tox -e do_format``. -* Run unit tests and/or linting checks pass using ``tox``. +* Ensure unit tests and/or linting checks pass using ``tox``. * Submit a PR against the ``main`` branch of the cloud-init repository. Debugging and reporting @@ -75,28 +75,6 @@ Debugging and reporting logging.rst debugging.rst -Transferring CLA Signatures from Launchpad to GitHub ----------------------------------------------------- - -If you signed the CLA 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 cloud-init repository to handle -this migration as automatically as possible. - -The 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 -account. - -.. note:: - - If you are a first time contributor, you will not need to do this. All new - CLA signatures are handled as part of the GitHub pull request process when - you make your first pull request. - - .. LINKS: .. include:: ../links.txt .. _quickstart documentation: https://docs.github.com/en/get-started/quickstart diff --git a/doc/rtd/development/style_docs.rst b/doc/rtd/development/style_docs.rst index bfed82c71417..ea73b8155597 100644 --- a/doc/rtd/development/style_docs.rst +++ b/doc/rtd/development/style_docs.rst @@ -109,7 +109,7 @@ Common words There are some common words that should follow specific usage in text: -- **Cloud-init**: Always hyphenated, and follows sentence case, so only +- **cloud-init**: Always hyphenated, and follows sentence case, so only capitalised at the start of a sentence. - **metadata**, **datasource**: One word. - **user data**, **vendor data**: Two words, not to be combined or hyphenated. diff --git a/doc/rtd/links.txt b/doc/rtd/links.txt index 42c56eec0eba..85cb5687f626 100644 --- a/doc/rtd/links.txt +++ b/doc/rtd/links.txt @@ -9,3 +9,5 @@ .. _Launchpad: https://launchpad.net .. _the docs: https://cloudinit.readthedocs.io/en/latest/ .. _tox: https://tox.readthedocs.io/en/latest/ +.. _Discourse: https://discourse.ubuntu.com/c/server/cloud-init/54 +.. _Github quickstart: https://docs.github.com/en/get-started/quickstart