Add CONTRIBUTING.rst

Signed-off-by: Niels Thykier <niels@thykier.net>

1 files changed, 191 insertions, 0 deletions

diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
new file mode 100644
index 00000000..ad4d58e6
--- /dev/null
+++ b/CONTRIBUTING.rst
@@ -0,0 +1,191 @@
+Contributing to debhelper
+=========================
+
+Thanks for your interest in improving debhelper.
+
+No matter how you identify yourself or how others perceive you: we
+welcome you. We welcome contributions from you as long as they
+interact constructively with our community.  See also :ref:`coc`.
+
+This document will cover what you need to get started on working with
+debhelper, where to submit patches or contributions and what we expect
+from contributors.
+
+.. contents::
+
+
+.. _getting-started:
+
+Getting started
+---------------
+
+This section helps you get started with working on debhelper.  It
+assumes you are comfortable with ``git``.
+
+First clone the debhelper git repository and install build-dependencies::
+
+  git clone https://salsa.debian.org/debian/debhelper.git
+  cd debhelper
+  apt-get build-dep ./
+  # Used for running the test suite
+  apt-get install perl
+
+Running the test suite::
+
+  # Available from the perl package.
+  prove -lr -j`nproc` t
+
+
+Doing a test build / release build of debhelper::
+
+  # Consider doing it in a chroot to verify that the Build-Depends are correct.
+  dpkg-buildpackage -us -uc
+  # installing it for further testing
+  apt-get install ../debhelper_<version>_all.deb
+
+
+Please have a look at ``doc/PROGRAMMING``, which have guidelines for
+debhelper code.
+
+Balancing simplicity, ease-of-use, performance, etc.
+----------------------------------------------------
+
+At times, there are conflicting wishes for debhelper.  We cannot
+satisfy all requirements and we sometimes have to say no thanks to a
+particular change because it conflicts with design goal, or if it is
+better suited in a different project, etc.
+
+Here are some guidelines that may be useful:
+
+ * New build systems or helpers that are language/framework specific
+   or have a narrow scope are generally better shipped in a separate
+   package.  If the scope becomes more general, the tooling can be
+   merged in to debhelper at a later stage.
+   - Examples: Most ``dh-*`` packages in Debian are examples of this.
+
+ * Changes that affect performance considerably generally must only
+   affect packages that need them and only affect a limited subset of
+   packages and a limited subset of ``dh_*``-tools.  Particularly, be
+   careful of ``Dpkg::*``-modules, which tend to have very high load
+   costs.
+
+ * Helpers / tools should generally `do the right thing` by default
+   (subject to backwards compatibility).  If most people neeed some
+   particular option to make the tool work for them, then the default
+   should be changed (again, subject to backwards compatibility).
+
+
+Handling backwards compatibility for consumers
+----------------------------------------------
+
+While changes in debhelper should avoid breaking consumers, some times
+we need to implement a backwards incompatible change (e.g. to improve
+defaults to match the current packaging norms or fix a bug).
+
+  * For non-trivial breakage, we use compat bumps and migrate to the new
+    functionality by default in the new major version of debhelper.
+    (see the ``compat`` function)
+
+  * For trivial issues or (mostly) unused functionality/bugs, then we
+    can make exceptions.  Preferably, have all consumers migrate away
+    from the feature being changed (ìn Debian ``unstable``) before
+    applying it.
+
+Note that we tend to support compat levels for a long time (10+
+years).  When changing behaviour via a compat bump, please take an
+extra look to ensure the change is sufficient (this is easier said
+than done).  See ``doc/SUPPORT-POLICY`` for more information.
+
+Debian support baseline for debhelper
+-------------------------------------
+
+The debhelper project aims to support the Debian ``unstable``,
+``testing``, and ``stable-backports`` suites by default.  For this to work,
+we work based on the following guidelines:
+
+  1) it should be trivial to use/Build-Depend on debhelper in
+     ``stable-backports``, and
+  2) the debhelper in ``stable-backports`` should behave the same as
+     in ``unstable``.
+
+In some cases, we can disable some minor functionality in
+``stable-backports`` (previous cases being ``dbgsym`` and ``R³``).
+
+Where possible, use versioned ``Breaks`` against other packages to
+make it easier to support packages in ``stable-backports``
+(e.g. debhelper had a ``Breaks`` against ``meson`` to ensure packages
+used a recent enough version of ``meson`` when using the debhelper
+from ``stretch-backports``).
+
+Submitting your contribution
+----------------------------
+
+We accept merge requests on https://salsa.debian.org/debian/debhelper
+and in general prfer these to bug reports with patches.  This is
+because the merge requests will run our CI to ensure the tests still
+pass.
+
+However, we fully respect that not everyone may want to sign up on a
+Debian service (e.g. it might be a steep overhead for a one-time
+contribution).  Therefore, we also accepts bug reports against the
+debhelper package in Debian with either patches (``git format-patch``
+format preferred) or links to public git repositories with reference
+to branches.  Please see :ref:`submitting-a-bug` for the guide on how
+to do that.
+
+Please see :ref:`getting-started` for how to obtain the source code
+and run the test suite.
+
+.. _submitting-a-bug:
+
+Submitting a bug report
+-----------------------
+
+If you want to submit a bug report against debhelper, please see
+https://www.debian.org/Bugs/Reporting for how to report the bug in the
+Debian bug tracker (please file it against the ``debhelper`` package).
+
+Users of Debian can use ``reportbug debhelper`` if they have the
+reportbug tool installed.
+
+You can find the list of open bugs against debhelper at:
+https://bugs.debian.org/src:debhelper
+
+.. _coc:
+
+Code of Conduct, Social rules and conflict resolution
+-----------------------------------------------------
+
+The debhelper suite is a part of Debian. Accordingly, the Code of
+Conduct, Social rules and conflict resolution applies to debhelper and
+all of its contributors.
+
+As a guiding principle, we strive to have an open welcoming community
+working on making Debian packaging easier.  Hopefully, this will be
+sufficient for most contributors.  For more details, please consider
+reading (some) of the documents below.
+
+
+ * `Debian's Code of Conduct <https://www.debian.org/code_of_conduct>`_
+   - If you feel a contributor is violating the code of contact, please
+     contact the `Debian anti-harassment team <https://wiki.debian.org/AntiHarassment>`_
+     if you are uncomfortable with engaging with them directly.
+
+ * `Debian's Diversity Statement <https://www.debian.org/intro/diversity>`_
+   - Note that `interact constructively with our community` has the
+     implication that contributors extend the same acceptance and
+     welcome to others as they can expect from others based on the
+     diversity statement.
+
+   - The rationale for this implication is based on the `Paradoc of tolerance <https://en.wikipedia.org/wiki/Paradox_of_tolerance>`_.
+     
+
+ * `Debian's Social Contract and Free Software Guidelines <https://www.debian.org/social_contract>`_.
+
+ * (very optional read) `Debian's Constitution <https://www.debian.org/devel/constitution>`_.
+   - The primary point of importance from this document is the
+     debhelper project is subject the Debian's technical committee and
+     the Debian General Resolution (GR) process.  These
+     bodies/processes can make decisions that the debhelper project
+     must follow.  Notably, the GR process is used for updating the
+     Debian documents above.