From Mageia wiki
Jump to: navigation, search
m (removed fancy quotes so that copy/paste works (especially mgarepo putsrpm))
 
(11 intermediate revisions by 8 users not shown)
Line 9: Line 9:
 
From time-to-time a new package may be requested or desirable in Mageia. If, as a packager, you decide to import a source rpm from another distribution, you should take care to ensure that the source rpm contains the full changelog section.  
 
From time-to-time a new package may be requested or desirable in Mageia. If, as a packager, you decide to import a source rpm from another distribution, you should take care to ensure that the source rpm contains the full changelog section.  
  
''Remember that packages generated via a rpmbuild -bs from a Mandriva or Mageia package checkout '''does not''' contain a changelog''
 
  
When importing the source rpm, mgarepo will automatically copy this changelog to a file called '''packages/misc/$newpackage.log''' in our subversion repository. When this package is subsequently built in the future it will include this pre-import changelog and thus properly represents is history prior to import. When running the command to import the source rpm the packager should also credit the origin: e.g.
+
''Remember that packages generated via a rpmbuild -bs from a Mandriva or Mageia package checkout '''do not''' contain a changelog''
 +
 
 +
 
 +
When importing the source rpm, mgarepo will automatically copy this changelog to a file called '''packages/misc/$newpackage/log''' in our subversion repository. When this package is subsequently built in the future it will include this pre-import changelog and thus properly represents its history prior to import. When running the command to import the source rpm the packager should also credit the origin: e.g.
 +
 
 +
 
 +
<code> mgarepo putsrpm -l "Import Fedora package" newpackage-1.2.3.src.rpm</code>
  
<code> mgarepo putsrpm -m “Import Fedora package” $newpackage-1.2.3.src.rpm</code>
 
  
 
This message (as any svn commit message) will ultimately end up in the auto-generated package changelog and thus publicly attributes the origin.
 
This message (as any svn commit message) will ultimately end up in the auto-generated package changelog and thus publicly attributes the origin.
Line 25: Line 29:
  
 
=== Upstream ===
 
=== Upstream ===
When including an upstream patch, it is highly preferred to use '''git format-patch style patches''' if the upstream project uses git as it's revision control system. This format of patch clearly shows the full commit message and contains the author information and any subsequent sign-off by any reviewers.   
+
When including an upstream patch, it is highly preferred to use '''git format-patch style patches''' if the upstream project uses git as its revision control system (while our package repository is ultimately based on subversion, the format of the patch files we keep in the package repository can still be those generated from git). This format of patch clearly shows the full commit message and contains the author information and any subsequent sign-off by any reviewers.   
  
 
The git format-patch command will automatically select a suitable, descriptive filename. If a patch is generated from an upstream subversion commit then it is preferred if the name of the patch file contains the revision number (e.g. '''newpackage-1.2.3-fix-widget-display-r12345.patch'''). Other, less common, revision control systems should be used in a similar way where ever possible.  
 
The git format-patch command will automatically select a suitable, descriptive filename. If a patch is generated from an upstream subversion commit then it is preferred if the name of the patch file contains the revision number (e.g. '''newpackage-1.2.3-fix-widget-display-r12345.patch'''). Other, less common, revision control systems should be used in a similar way where ever possible.  
Line 34: Line 38:
 
When including a patch from another distribution, packagers should first check to see if that patch has already been upstreamed and, if so, use the rules listed above. If the patch is not yet usptreamed, it should be copied from the other distribution but care should be taken when committing the patch to mention the origin – e.g.:
 
When including a patch from another distribution, packagers should first check to see if that patch has already been upstreamed and, if so, use the rules listed above. If the patch is not yet usptreamed, it should be copied from the other distribution but care should be taken when committing the patch to mention the origin – e.g.:
  
<code> “Apply patch from Mandriva to fix build under gcc x.y.z”</code>
 
  
Ideally the patch itself will be git formatted and thus contain the actual author information for easy reference. However we deem it more important to credit the organisation than the individual author in our package commit messages. It should be possible to follow the chain back to the individual in most cases if such information required in the future and is not available directly in the patch itself. Of course sometimes the other distribution may themselves include a patch from another distribution!. If this is clear to see, the packager should try and follow the chain as far as possible, however the distribution first looked at still deserves credit for providing easy access to the fix in the first place, so absolute resolution of any chains is not a strict requirement.
+
<code> "Apply patch from Mandriva to fix build under gcc x.y.z"</code>
 +
 
 +
 
 +
Ideally the patch itself will be git formatted and thus contain the actual author information for easy reference. However we deem it more important to credit the organisation than the individual author in our package commit messages. It should be possible to follow the chain back to the individual in most cases if such information is required in the future and is not available directly in the patch itself. Of course, sometimes the other distribution may themselves include a patch from another distribution! If this is clear to see, the packager should try and follow the chain as far as possible, however the distribution first looked at still deserves credit for providing easy access to the fix in the first place, so absolute resolution of any chains is not a strict requirement.
  
If a patch in another distribution looks like it is relevant for upstream inclusion but has not yet been posted to an upstream project, packages should try and enquire about this where ever possible. Patches may have been added and subsequently forgotten about by the packager in the other distribution, so encouraging upstream submission is sometimes beneficial for everyone.
+
If a patch in another distribution looks like it is relevant for upstream inclusion but has not yet been posted to an upstream project, packagers should try and enquire about this wherever possible. Patches may have been added and subsequently forgotten about by the packager in the other distribution, so encouraging upstream submission is sometimes beneficial for everyone.
  
 
=== Upstream Communities ===
 
=== Upstream Communities ===
 
Any patch proposed by a contributor directly to an upstream project (e.g via their bug tracker or mailing list etc.) should be credited in a similar way to patches from other distributions. e.g.:
 
Any patch proposed by a contributor directly to an upstream project (e.g via their bug tracker or mailing list etc.) should be credited in a similar way to patches from other distributions. e.g.:
  
<code> “Apply patch from XBMC mailing list to add support for BBC iPlayer”</code>
+
 
 +
<code> "Apply patch from XBMC mailing list to add support for BBC iPlayer"</code>
 +
 
  
 
Again, if a patch looks forgotten or uncommented on by upstream developers it would be nice to send a “ping” email/comment to chase up the upstreaming process.
 
Again, if a patch looks forgotten or uncommented on by upstream developers it would be nice to send a “ping” email/comment to chase up the upstreaming process.
Line 63: Line 71:
 
As outlined above, the general approach we would like to encourage is that of collaboration whenever possible. We actively encourage packagers to speak and liaise directly with upstream projects and packagers from other distributions. Reporting bugs or security problems on other distributions bug reporting tools when problems are found in patches they apply or software they develop is also encouraged. Try be a good citizen in the free software community and always try to encourage upstreaming of fixes and features whenever possible.
 
As outlined above, the general approach we would like to encourage is that of collaboration whenever possible. We actively encourage packagers to speak and liaise directly with upstream projects and packagers from other distributions. Reporting bugs or security problems on other distributions bug reporting tools when problems are found in patches they apply or software they develop is also encouraged. Try be a good citizen in the free software community and always try to encourage upstreaming of fixes and features whenever possible.
  
From time-to-time, it is inevitable that disagreements will occur. '''While this document is not intended to impose any kind of behaviour guidelines, please try to keep in mind that you may be seen to be representing the Mageia community, even if the opinions are yours alone.''' While some comments from others may anger you or feel like personal attacks and insults, it is often still far better to simply not reply or get dragged into a flame war which rarely have positive outputs for either party. Often discretion is the better part of valour!
+
From time-to-time, it is inevitable that disagreements will occur. '''While this document is not intended to impose any kind of behaviour guidelines, please try to keep in mind that you may be seen to be representing the Mageia community, even if the opinions are yours alone.''' While some comments from others may anger you or feel like personal attacks and insults, it is often still far better to simply not reply or get dragged into a flame war which will rarely have a positive outcome for either party. Often discretion is the better part of valour!
  
 
We hope you are proud to be part of the Mageia community. And by following the above guidelines, we are confident that everyone who is part of the Mageia community will always be very grateful for and proud of your involvement. Happy hacking!
 
We hope you are proud to be part of the Mageia community. And by following the above guidelines, we are confident that everyone who is part of the Mageia community will always be very grateful for and proud of your involvement. Happy hacking!

Latest revision as of 19:59, 23 October 2012

Introduction

Collaboration is one of the key principles that underpins what Mageia represents. We are a relatively small collection of contributors and working with other distributions and upstream projects is actively encouraged whenever possible.

Outlined below are a set of basic guidelines that are based mostly on common sense, but spell out clearly the general behaviour expected of every Mageia contributor.

Packages

From time-to-time a new package may be requested or desirable in Mageia. If, as a packager, you decide to import a source rpm from another distribution, you should take care to ensure that the source rpm contains the full changelog section.


Remember that packages generated via a rpmbuild -bs from a Mandriva or Mageia package checkout do not contain a changelog


When importing the source rpm, mgarepo will automatically copy this changelog to a file called packages/misc/$newpackage/log in our subversion repository. When this package is subsequently built in the future it will include this pre-import changelog and thus properly represents its history prior to import. When running the command to import the source rpm the packager should also credit the origin: e.g.


mgarepo putsrpm -l "Import Fedora package" newpackage-1.2.3.src.rpm


This message (as any svn commit message) will ultimately end up in the auto-generated package changelog and thus publicly attributes the origin.

All Mageia packages are publicly available via our subversion repository and other distributions are obviously welcome to use these packages as needed. If you copy the spec wholesale or take large chunks of it (e.g. perhaps a non-trivial %post script or similar), we would very much appreciate a similar “origin attribution” as outlined above in your own packages repository.

Such attribution not only credits the work of others, it also serves as an important log for future packagers. If looking for updates or investigating problems it's usually useful to check if any update or fix is already available elsewhere. Knowing the origin simply by looking at the repository history can aid this process.

Patches

Whether it be a bugfix or an experimental or highly desirable feature, many packages will contain patches. The most common sources of any non-trivial, non-buildfix patch are upstream and from other distributions.

Upstream

When including an upstream patch, it is highly preferred to use git format-patch style patches if the upstream project uses git as its revision control system (while our package repository is ultimately based on subversion, the format of the patch files we keep in the package repository can still be those generated from git). This format of patch clearly shows the full commit message and contains the author information and any subsequent sign-off by any reviewers.

The git format-patch command will automatically select a suitable, descriptive filename. If a patch is generated from an upstream subversion commit then it is preferred if the name of the patch file contains the revision number (e.g. newpackage-1.2.3-fix-widget-display-r12345.patch). Other, less common, revision control systems should be used in a similar way where ever possible.

These techniques help to aid clarity over the origin of the change. This is beneficial both for Mageia packagers in the future, and for other distributions looking at our packages for any bugfixes.

Other Distributions

When including a patch from another distribution, packagers should first check to see if that patch has already been upstreamed and, if so, use the rules listed above. If the patch is not yet usptreamed, it should be copied from the other distribution but care should be taken when committing the patch to mention the origin – e.g.:


"Apply patch from Mandriva to fix build under gcc x.y.z"


Ideally the patch itself will be git formatted and thus contain the actual author information for easy reference. However we deem it more important to credit the organisation than the individual author in our package commit messages. It should be possible to follow the chain back to the individual in most cases if such information is required in the future and is not available directly in the patch itself. Of course, sometimes the other distribution may themselves include a patch from another distribution! If this is clear to see, the packager should try and follow the chain as far as possible, however the distribution first looked at still deserves credit for providing easy access to the fix in the first place, so absolute resolution of any chains is not a strict requirement.

If a patch in another distribution looks like it is relevant for upstream inclusion but has not yet been posted to an upstream project, packagers should try and enquire about this wherever possible. Patches may have been added and subsequently forgotten about by the packager in the other distribution, so encouraging upstream submission is sometimes beneficial for everyone.

Upstream Communities

Any patch proposed by a contributor directly to an upstream project (e.g via their bug tracker or mailing list etc.) should be credited in a similar way to patches from other distributions. e.g.:


"Apply patch from XBMC mailing list to add support for BBC iPlayer"


Again, if a patch looks forgotten or uncommented on by upstream developers it would be nice to send a “ping” email/comment to chase up the upstreaming process.

Written By Us

It should go without saying, but any patches written by Mageia contributors should be submitted upstream whenever possible and appropriate. As the author you are free to use any identity you see fit, however you may wish to use your @mageia.org email address as this may provide an indication that the fix itself has been tested and deployed already, and also may provide a general point of contact should any follow-up questions be asked when the original author is unavailable.

Artwork

As with software packages, the license restrictions of any artwork included in Mageia obviously have to be respected. Even when the license does not strictly require attribution of the source we should always aim to include this detail if appropriate.


Individuals vs. Organisations

As a general rule, it is typically more useful with regards to historical reference to ensure the organisation or community as a whole is referenced in commit messages. While it may be nice to credit individuals in such public messages, such information is, of itself, not that useful for future follow ups. As mentioned above, the use of git formatted patches is highly encouraged as this will contain the original author information.

When making commits to software repositories (i.e. non-packages), it can often be very difficult to ensure that full author attribution is maintained as the tools used to perform such tasks need significant manual intervention to achieve this goal. The use of git is highly encouraged here which makes this process incredibly easy and basically built-in.


General Behaviour

As outlined above, the general approach we would like to encourage is that of collaboration whenever possible. We actively encourage packagers to speak and liaise directly with upstream projects and packagers from other distributions. Reporting bugs or security problems on other distributions bug reporting tools when problems are found in patches they apply or software they develop is also encouraged. Try be a good citizen in the free software community and always try to encourage upstreaming of fixes and features whenever possible.

From time-to-time, it is inevitable that disagreements will occur. While this document is not intended to impose any kind of behaviour guidelines, please try to keep in mind that you may be seen to be representing the Mageia community, even if the opinions are yours alone. While some comments from others may anger you or feel like personal attacks and insults, it is often still far better to simply not reply or get dragged into a flame war which will rarely have a positive outcome for either party. Often discretion is the better part of valour!

We hope you are proud to be part of the Mageia community. And by following the above guidelines, we are confident that everyone who is part of the Mageia community will always be very grateful for and proud of your involvement. Happy hacking!