docs: Rename HACKING.rst to CONTRIBUTING.rst (canonical#1118)

TheRealFalcon · web-flow · commit b36b4e2fde2c · 2021-11-22T16:17:26.000-07:00
This is more consistent with other github repositories, and will prompt
a first-time contributor to read the contributing guidelines before
submitting the pull request.

Additionally, added a summary section to the top, updated some outdated
language, and removed some outdated typing guidance.
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
@@ -1,6 +1,5 @@
-*********************
-Hacking on cloud-init
-*********************
+Contributing to cloud-init
+**************************
 
 This document describes how to contribute changes to cloud-init.
 It assumes you have a `GitHub`_ account, and refers to your GitHub user
@@ -9,6 +8,26 @@ as ``GH_USER`` throughout.
 Submitting your first pull request
 ==================================
 
+Summary
+-------
+
+Before any pull request can be accepted, you must do the following:
+
+* Sign the Canonical `contributor license agreement`_
+* Add yourself (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 tests`_ (if applicable)
+* Ensure unit tests and linting pass using `tox`_
+* Submit a PR against the `main` branch of the `cloud-init` repository
+
+.. _unit tests: https://cloudinit.readthedocs.io/en/latest/topics/testing.html
+.. _integration tests: https://cloudinit.readthedocs.io/en/latest/topics/integration_tests.html
+
+The detailed instructions
+-------------------------
+
 Follow these steps to submit your first pull request to cloud-init:
 
 * To contribute to cloud-init, you must sign the Canonical `contributor
@@ -78,7 +97,6 @@ Follow these steps to submit your first pull request to cloud-init:
 .. _repository: https://github.com/canonical/cloud-init
 .. _contributor license agreement: https://ubuntu.com/legal/contributors
 .. _contributor-agreement-canonical: https://launchpad.net/%7Econtributor-agreement-canonical/+members
-.. _tools/.github-cla-signers: https://github.com/canonical/cloud-init/blob/main/tools/.github-cla-signers
 .. _PR #344: https://github.com/canonical/cloud-init/pull/344
 .. _PR #345: https://github.com/canonical/cloud-init/pull/345
 
@@ -123,7 +141,7 @@ Do these things for each feature or bug
 
     git push -u GH_USER my-topic-branch
 
-* Use your browser to create a merge request:
+* Use your browser to create a pull request:
 
   - Open the branch on GitHub
 
@@ -142,28 +160,30 @@ Do these things for each feature or bug
       as footers with syntax as shown here.
 
       The commit message should be one summary line of less than
-      74 characters followed by a blank line, and then one or more
-      paragraphs describing the change and why it was needed.
+      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 sqaushed and merged into trunk.
+      is sqaushed and merged into main. If there is a related launchpad
+      bug, specify it at the bottom of the commit message.
 
-      LP: #1
+      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`
 
-Then, someone in the `Ubuntu Server`_ team will review your changes and
+Then, a cloud-init committer will review your changes and
 follow up in the pull request.  Look at the `Code Review Process`_ doc
 to understand the following steps.
 
 Feel free to ping and/or join ``#cloud-init`` on Libera irc if you
 have any questions.
 
 .. _tox: https://tox.readthedocs.io/en/latest/
-.. _Ubuntu Server: https://github.com/orgs/canonical/teams/ubuntu-server
 .. _Code Review Process: https://cloudinit.readthedocs.io/en/latest/topics/code_review.html
 
 Design
@@ -188,18 +208,9 @@ Type Annotations
 ----------------
 
 The cloud-init codebase uses Python's annotation support for storing
-type annotations in the style specified by `PEP-484`_.  Their use in
-the codebase is encouraged but with one important caveat: types from
-the ``typing`` module cannot be used.
-
-cloud-init still supports Python 3.4, which doesn't have the ``typing``
-module in the stdlib.  This means that the use of any types from the
-``typing`` module in the codebase would require installation of an
-additional Python module on platforms using Python 3.4.  As such
-platforms are generally in maintenance mode, the introduction of a new
-dependency may act as a break in compatibility in practical terms.
-
-Similarly, only function annotations are appropriate for use, as the
+type annotations in the style specified by `PEP-484`_. Their use in
+the codebase is encouraged but with one important caveat: only
+function annotations or comment annotations are supported, as the
 variable annotations specified in `PEP-526`_ were introduced in Python
 3.6.
 
@@ -517,6 +528,7 @@ References
 * `PR #363`_, the discussion which prompted finally starting this
   refactor (and where a lot of the above details were hashed out)
 
+.. _tools/.github-cla-signers: https://github.com/canonical/cloud-init/blob/main/tools/.github-cla-signers
 .. _get_interfaces_by_mac: https://github.com/canonical/cloud-init/blob/961239749106daead88da483e7319e9268c67cde/cloudinit/net/__init__.py#L810-L818
 .. _Mina Galić's email the the cloud-init ML in 2018: https://lists.launchpad.net/cloud-init/msg00185.html
 .. _Mina Galić's email to the cloud-init ML in 2019: https://lists.launchpad.net/cloud-init/msg00237.html
diff --git a/doc/rtd/index.rst b/doc/rtd/index.rst
@@ -68,7 +68,7 @@ Having trouble? We would like to help!
    :titlesonly:
    :caption: Development
 
-   topics/hacking.rst
+   topics/contributing.rst
    topics/code_review.rst
    topics/security.rst
    topics/debugging.rst
diff --git a/doc/rtd/topics/contributing.rst b/doc/rtd/topics/contributing.rst
@@ -0,0 +1,2 @@
+.. include:: ../../../CONTRIBUTING.rst
+.. vi: textwidth=78
diff --git a/doc/rtd/topics/hacking.rst b/doc/rtd/topics/hacking.rst

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+.. include:: ../../../CONTRIBUTING.rst`
	`2`	`+.. vi: textwidth=78`