Contribute.mdwn 9.37 KB
Newer Older
Alexander Wirt's avatar
Alexander Wirt committed
1 2 3 4 5
[[!toc  startlevel=2 levels=2]]

##Packaging

###Introduction 
Alexander Wirt's avatar
Alexander Wirt committed
6
The packages on debian-backports are made by volunteers. If you
Alexander Wirt's avatar
Alexander Wirt committed
7 8 9
like to help with backporting packages from the Debian archive, make sure you
follow these guidelines. 

Alexander Wirt's avatar
Alexander Wirt committed
10 11 12 13
##Uploading

###Debian Developers

Alexander Wirt's avatar
Alexander Wirt committed
14
All Debian Developers (DD) can get their uid into the backports ACL. If
15 16
you want to get include please open a ticket in the debian [request
tracker](https://rt.debian.org/Ticket/Create.html?Queue=20)
17
- please use the backports queue for the ticket. (See
18
[wiki](https://wiki.debian.org/rt.debian.org) for more information about the
19
request tracker). Once your UID is added, wait an hour for the cronjob to import your upload rights and you can start uploading.
Alexander Wirt's avatar
Alexander Wirt committed
20

21
The upload happens in the same way as normal uploads to the archive happens,
Alexander Wirt's avatar
Alexander Wirt committed
22 23
just the distribution have to match one of the backports distributions (jessie-backports,
jessie-backports-sloppy, stretch-backports)
Alexander Wirt's avatar
Alexander Wirt committed
24

25 26 27
**The special host in dupload/dput that was needed in the past is now obsolete and doesn't work
anymore.**

28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49
###Debian Maintainers

Debian Maintainers (DM) can also get their uid into the backports ACL.
Please follow the instructions for Debian Developers.

Please note that:

* Any upload of a package that has to pass through the backports NEW
  queue (e.g. package not already in that specific backports suite,
  package adds a new binary package, etc.) needs to be sponsored by a
  Debian Developer and cannot be done by a Debian Maintainer themselves.
  (Same as uploading to unstable.) Otherwise, DMs may upload directly.
* The Debian Maintainer needs to have upload rights for the specific
  package they want to upload to backports (the same right they need for
  uploading that package to unstable), otherwise the upload will not
  succeed. Therefore, if you are a DM that isn't also maintaining the
  package in unstable, please talk to the regular maintainer first before
  requesting upload rights for that package. (It is considered good
  practice to inform the maintainer regardless, see below.) See the
  [DebianMaintainer page in the Debian wiki](https://wiki.debian.org/DebianMaintainer#Granting_Permissions)
  for instructions for DDs on how to give upload rights to DMs.

50
###Non Debian Developer
Alexander Wirt's avatar
Alexander Wirt committed
51 52 53 54 55

If you are not a Debian Developer, please upload your backport somewhere
(binaries and sources, e.g. to mentors.debian.net), post a link to its .dsc
file on <debian-backports@lists.debian.org> and ask for review and upload.

56 57
### Some important note

Alexander Wirt's avatar
Alexander Wirt committed
58 59 60 61
Please note, that you are responsible for this backport from the time on when
it was accepted on debian-backports. This means, you have to keep track of the
changes in unstable, update your backport when a new version enters testing and
provide security updates when needed. If you are not willing or capable of
62
doing this, you better ask someone else (e.g. on the mentioned mailing list) to
Alexander Wirt's avatar
Alexander Wirt committed
63 64
create and maintain the backport. 

Alexander Wirt's avatar
Alexander Wirt committed
65 66 67 68 69
###Supported Distributions

The following distributions are supported for backports. Please don't use
unstable or stable as target distribution.

70 71
| Source Distribution | Backports Distribution                      | Version suffix       |
|---------------------|---------------------------------------------|----------------------|
Alexander Wirt's avatar
Alexander Wirt committed
72 73
| stretch              | jessie-backports                            | ~bpo8+1             |
| buster             | stretch-backports or jessie-backports-sloppy | ~bpo9+1 or ~bpo8+1   |
Alexander Wirt's avatar
Alexander Wirt committed
74 75


Alexander Wirt's avatar
Alexander Wirt committed
76 77
###Basic Rules 

78
* [Subscribe to the backports mailing list](https://lists.debian.org/debian-backports/). Every announcement and bug report should come over this mailing list, so this is a must.
79
* Make sure that you have a proper build environment that only contains the suite for which the backport is for (e.g. jessie if you want to upload to jessie-backports) and no unneeded backports. Maybe you want to consider pbuilder or cowbuilder for building packages.
Alexander Wirt's avatar
Alexander Wirt committed
80
* Append "~bpo${debian_release}+${build_int}" to the version number, e.g. "1.2.3-4" now becomes "1.2.3-4~bpo8+1", or for native packages, "1.2.3" becomes "1.2.3~bpo8+1".
81
* Please only upload package with a notable userbase. User request for the package may be an indicator.
Alexander Wirt's avatar
Alexander Wirt committed
82 83 84 85
* Don't backport minor version changes without any user visible changes or bugfixes
* To guarantee an upgrade path from stable+backports to the next stable, the
package should be in testing.. Of course there are some exceptions: Security
updates. If your package had a security update you can upload a new backport
Alexander Wirt's avatar
Alexander Wirt committed
86 87 88 89
even if its not yet in testing. If you have good reasons to update a package
which is already is in backports with a newer version from unstable (which is
intended for testing), come and speak to us. Common exceptions are: critical
bugs fixed, library transitions.
Alexander Wirt's avatar
Alexander Wirt committed
90
* Do not do any changes to the package beside of backporting stuff.
Rhonda D'Vine's avatar
Rhonda D'Vine committed
91
* It is recommended to include all changelog entries since the last version on
Alexander Wirt's avatar
Alexander Wirt committed
92 93 94
  debian-backports or since stable if it's the first version. You should do
  this by passing "-v<version>" to dpkg-buildpackage. Eg: "debuild -v0.7.5-2",
  where "0.7.5-2" is the version in stable. If the package wasn't in stable or
95
  backports before you don't have include the changelog entries (but you are
Alexander Wirt's avatar
Alexander Wirt committed
96
  free to do so). It helps others to follow the changes introduced with the
97
  backport (by reading the changes mailing list).
Alexander Wirt's avatar
Alexander Wirt committed
98
* Before uploading please think about how useful the package is for stable
99 100 101 102
  users and if you want to support the package until support for the
  distribution you uploaded ends. You should consider adding yourself to the
  Uploaders field of the debian/control file or subscribing to the package
  though PTS. What is important is that you track the package for the lifetime
Alexander Wirt's avatar
Alexander Wirt committed
103
  of the release cycle (stable and oldstable).
104 105 106
* Backports of an updated version of a package that was backported before
  *may* have a changelog that merges entries of backports of previous versions,
  but this is **not required**.
107 108 109
* If the packages lists a VCS in the debian/control file, please ask the maintainer
of the package to add your changes there, or ask for permission to do it yourself.

Alexander Wirt's avatar
Alexander Wirt committed
110

111
If you feel you would need to diverge from these rules, either discuss it on the [mailing list](https://lists.debian.org/debian-backports/) or bring it up with the [Backports Team](mailto:backports-team@debian.org) for an exception.
112

113

114 115 116
###Uploads for old-stable backports

With the release of a new stable version uploading packages with versions greater than in new stable or
117
new stable-security are not allowed. If you want newer package versions in old-stable-backports we created a
Alexander Wirt's avatar
Alexander Wirt committed
118 119
new suite for that: oldstable-backports-sloppy. So if you want to upload a package from buster to jessie-backports
use jessie-backports-sloppy as target distribution.
120

Alexander Wirt's avatar
Alexander Wirt committed
121 122 123 124 125 126 127 128 129 130 131 132
###Additionally

* Do not lower the standards version, it is just useless.
* Do not add lintian/linda overrides to suppress the 'wrong-distribution'
warnings.
* Do always look at the interdiff between the testing version and the backports
version, keep in mind that it should be as minimal as possible.
* Do write good changelogs and document all changes you needed to do in order
to make it run on stable.

##Security Uploads

Alexander Wirt's avatar
Alexander Wirt committed
133 134 135 136 137
If you upload a package which fixes security related problem please create a
ticket in the debian [request tracker](https://rt.debian.org/Ticket/Create.html?Queue=20)
- please use the backports queue for the ticket. (See
[wiki](https://wiki.debian.org/rt.debian.org) for more information about the
request tracker). 
138

Alexander Wirt's avatar
Alexander Wirt committed
139 140 141
Please follow the following template and provide us with the required
information to write a BSA. Please don't wait for the BSA and upload
immediatly. 
Alexander Wirt's avatar
Alexander Wirt committed
142

143
    Subject: [BSA-XXX] Security Update for <packagename>
Alexander Wirt's avatar
Alexander Wirt committed
144 145 146 147 148 149 150 151 152 153
      
    <Uploader> uploaded new packages for <packagename> which fixed the
    following security problems:
    
    CVE-XXXX or whatever ID if existant
      short description 
      ...
    CVE-.... 
      ....

Alexander Wirt's avatar
Alexander Wirt committed
154
    For the stretch-backports distribution the problems have been fixed in
Alexander Wirt's avatar
Alexander Wirt committed
155 156 157 158 159 160 161 162
    version <packageversion>.

    <other distributions if any> 
  
##Best Practice

###Check NEW queue

163
Check the NEW queue at <https://ftp-master.debian.org/backports-new.html> to avoid
Alexander Wirt's avatar
Alexander Wirt committed
164 165 166 167
double efforts before you start to backport something. 

###Inform the Maintainer 

168 169 170
It is a good idea to contact the maintainer of the package in Debian prior to
your upload to let them know or even share ideas and common pitfalls (like
special dependencies). If you are not already
171
[subscribed](https://lists.debian.org/debian-backports) to
Alexander Wirt's avatar
Alexander Wirt committed
172
<debian-backports@lists.debian.org>, please do so. There might be
Alexander Wirt's avatar
Alexander Wirt committed
173
questions/problems from users regarding your backport(s) which you can answer
174
best and hopefully solve. Also it is adviced to subscribe to the bug reports for
175
the package through the [PTS](https://packages.qa.debian.org/) to be notified
176 177
about issues that potential affect the backport too and would be a good reason
to update the backports.
Alexander Wirt's avatar
Alexander Wirt committed
178 179 180

###Inform the Backporter 

Alexander Wirt's avatar
Alexander Wirt committed
181
If there is already a backport of your package of choice but it's outdated and you want to update it please inform the person who backported the last accepted version about your intentions. You can get the information from <https://backports.debian.org/changes/stretch-backports.html>
Alexander Wirt's avatar
Alexander Wirt committed
182 183 184 185 186

###Uploaders

If you put yourself into the Uploaders: field in debian/control you can easily
track your backports on the package overview at
187 188
<https://qa.debian.org/developer.php>. Alternatively you can use the
[subscribe feature](https://qa.debian.org/developer.php#subscribe) of the DDPO
Rhonda D'Vine's avatar
Rhonda D'Vine committed
189
to have them listed.