summaryrefslogtreecommitdiffstats
path: root/CONTRIBUTING.md
diff options
context:
space:
mode:
Diffstat (limited to 'CONTRIBUTING.md')
-rw-r--r--CONTRIBUTING.md194
1 files changed, 194 insertions, 0 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..791c2ea
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,194 @@
+# 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 [Code of
+Conduct, Social rules and conflict
+resolution](#code-of-conduct-social-rules-and-conflict-resolution).
+
+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.
+
+
+## Getting started
+
+<a id="getting-starting"></a>
+
+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 need 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 (in 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 `testing` when backporting a package from `testing`.
+
+ * Note that we do not require feature/bug compatibility with
+ debhelper in `stable` (as most packages will still use
+ debhelper from `stable`).
+
+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 [salsa.debian.org] and in general prefer
+these to bug reports with patches. This is because the merge requests
+will run our CI to ensure the tests still pass. When opening a merge
+request, please consider allowing committers to edit the branch as
+this enables us to rebase it for you.
+
+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 [Submitting a bug
+report](#submitting-a-bug-report) for the guide on how to do that.
+
+Please see [getting started](#getting-started) for how to obtain the
+source code and run the test suite.
+
+[salsa]: https://salsa.debian.org/debian/debhelper
+
+
+## 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]().
+
+
+## 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 from Debian 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.