File: CONTRIBUTING.rst

package info (click to toggle)
debhelper 12.1.1
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 4,072 kB
  • sloc: perl: 10,850; makefile: 120; sh: 8
file content (201 lines) | stat: -rw-r--r-- 7,848 bytes parent folder | download | duplicates (2)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
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:`code-of-conduct`.

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 ``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 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.  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 :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

.. _code-of-conduct:

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.