+ ** xref:Policy_for_encouraging_comaintainers_of_packages.adoc[Policy for encouraging comaintainers of packages]

+ = Policy for encouraging comaintainers of packages

+ :toc:

+ 

+ == Digest

+ 

+ All packages in Fedora

+ should normally be maintained by a group of maintainers.

+ Ideally,

+ each package should have at least three maintainers.

+ There is one primary maintainer

+ and a primary maintainer per distribution release.

+ Often both will be identical.

+ Each distribution maintainer

+ should have at least one co-maintainer per release,

+ to make sure there are actually at least two people

+ for a package

+ per each supported release.

+ Maintainers should work towards

+ getting at least one co-maintainer.

+ 

+ One important goal of co-maintainership in Fedora

+ is to help getting new people involved into the project.

+ Another is to reduce the burden of experienced and respected maintainers

+ so they get a chance to get involved with

+ more complicated and important parts of the project

+ if they want to.

+ 

+ == Policy

+ 

+ All packages in Fedora shall normally be maintained

+ by a group of maintainers.

+ The most important reasons for this rule are:

+ 

+ * One maintainer can commit fixes

+ like patches or new upstream releases that fix important bugs

+ (for example security data-corruption issues

+ or packaging bugs that confuse the users' systems)

+ even when the other maintainer(s) are away from the keyboard

+ due to traveling, sleeping or whatever.

+ 

+ * Maintainers further can help, guide and watch each other,

+ which should lead to better overall package quality.

+ 

+ The goal is to have at least three maintainers per package

+ and at least two per supported distribution release.

+ Big and important packages should have more maintainers

+ -- there is no upper limit.

+ 

+ There is a primary maintainer who takes care of the package in general.

+ It is their job to approve and find new maintainers

+ and to make sure their efforts get coordinated,

+ especially between different branches like EPEL and Fedora.

+ 

+ There is a primary maintainer per distribution release.

+ That is often the same as the primary maintainer.

+ Bugs get assigned to the per distribution maintainer,

+ who is in charge of the package.

+ It does not mean that they have to do all the work,

+ but they have to make sure the work gets done!

+ 

+ The maintainers should actively work towards

+ getting at least one co-maintainer

+ and also try to get a second one.

+ That means asking on the mailing list now and then

+ for people that might be interested in the job.

+ The goal is to have that process mostly automated

+ -- e.g. let a script parse the owner information now and then

+ and send out the list of the packages

+ that do not have enough co-maintainers yet

+ to a mailing list.

+ 

+ The primary maintainer can't block co-maintainers for a distribution

+ only because they do not want to support that distribution

+ -- e.g. if they do not want to care about their package in EPEL,

+ they have to accept somebody else takes care of the package in EPEL.

+ 

+ == Guidelines

+ 

+ The following sections up until the end of this document

+ describe some guidelines how co-maintainership should be used in practice.

+ Note that the section title is "guidelines", and not "rules".

+ In other words:

+ you do not have to follow the guidelines if you have a good reason.

+ But please keep in mind

+ that they were carefully written

+ to take the interest of the project as a whole into account,

+ to make sure Fedora stays healthy and grows up

+ -- that might not be obvious on the first sight.

+ Thanks for helping us with it.

+ 

+ [[how_is_it_supposed_to_work_in_detail]]

+ === How is it supposed to work in detail

+ 

+ Something like the following points describe the concept roughly:

+ 

+ * In most cases the primary maintainer

+ is the primary per-release maintainer

+ for all supported distributions.

+ There are two co-maintainers.

+ The three make sure everybody knows the important stuff

+ and they share the load,

+ to make sure everybody knows about the details of the package.

+ 

+ * The primary maintainer should normally be

+ the primary per-release maintainer for the Fedora devel branch,

+ as that is the most important one.

+ 

+ * All maintainers of a particular package

+ should be co-maintainers or observers

+ (somebody that gets CCed to bugs

+ and get noticed of commits and builds,

+ but normally doesn't do any work)

+ for the Fedora devel branch,

+ as that's where all the fun stuff happens.

+ 

+ * The per-release primary maintainer

+ takes care of the a package for that release.

+ They should have at least one co-maintainer

+ for maintaining that package in that release.

+ 

+ * Bugs get assigned to the primary per-release maintainer.

+ The primary maintainer and the co-maintainer for that release

+ get into the CC list.

+ The per-release maintainer has to make sure the bugs get fixed,

+ but of course some of the other maintainers of that package can do that, too.

+ 

+ * All maintainers should check each others commits for correctness and sanity.

+ 

+ * The primary maintainer should make sure that

+ important bugfixes get applied

+ to all the supported distributions

+ as needed.

+ 

+ * For the devel branch:

+ ** Small changes

+ (for example: package enhancements, bugfixes)

+ and medium sized changes

+ (for example: update from 1.0.1 to 1.0.2)

+ go directly to cvs and get built.

+ If someone feels unsure about a commit

+ they should wait one or two days

+ before actually building

+ or pushing the package out to the repos,

+ as that should give the other maintainers a chance

+ to yell if they see problems.

+ ** Big changes

+ (for example:

+ update from 1.0.1 to 1.2.0

+ or heavy changes in the spec file)

+ should normally get coordinated between the different maintainers;

+ a temporary separate branch in the cvs, e-mail or bugzilla

+ can be used for this purpose.

+ 

+ * For released distributions:

+ Small changes

+ (for example: package enhancements, bugfixes)

+ get go directly to cvs.

+ The other maintainers of that package

+ should have the chance

+ (e.g. a short time period, like two days)

+ where they can commit other enhancements

+ (to save users lots of upgrades)

+ or to discuss the committed change

+ before its actually pushed to the users.

+ With the current (FC7T1) scheme it means:

+ don't build the package immediately.

+ (In the future with the new repo push stuff from lmacken

+ it hopefully should be easily possible

+ to define a waiting period in updates-testing

+ before a package gets pushed out to the proper repo.)

+ Only the per-distribution maintainer

+ should commit and build medium sized changes.

+ Those should be tested in devel first

+ and co-maintainers should have a chance

+ to comment on the commits

+ before the package gets in the repo.

+ Big changes get coordinated.

+ 

+ * The usual rules for https://fedoraproject.org/wiki/Who_is_allowed_to_modify_which_packages[modifying other people packages] remain intact.

+ Thus people from QA, Security or Arch-SIGs might touch the package, too.

+ There is the strong wish to have

+ a group of long-term contributors

+ (say FESCo members, Release-Managers, Sponsors and some other hand-selected people)

+ that get access everywhere

+ to commit package updates easily

+ without asking the maintainers,

+ in case the maintainers are not fixing stuff

+ or if the changes are small and obvious

+ (it's often a lot easier to commit a simple spec files touch

+ than to create a patch, send it to the maintainer or open bugzilla).

+ 

+ * The primary maintainer has to approve new co-maintainers.

+ They now and then should search for co-maintainers

+ if there aren't enough.

+ 

+ [[coordination_between_maintainers]]

+ === Coordination between maintainers

+ 

+ The primary maintainer can set individual guidelines

+ on what their co-maintainers are allowed and not allowed to do.

+ They have to put the rules into a file `rules`

+ in the package's top level directory

+ of the version control system

+ (e.g. `packagename/rules`).

+ These rules are optional

+ and should only be set in place

+ if there is a strong need.

+ We do not want different rules for each package,

+ as that will result in a major pita.

+ When you do so

+ please keep the goals of the project as a whole in mind.

+ The Fedora Distribution in a big *community* project

+ and keeping it running

+ is not much helped by

+ "This is my package, I don't want other people touching it" attitude.

+ 

+ === Disputes

+ 

+ In the past we had some conflicts

+ between the package maintainers

+ and other users and contributors

+ on how to best maintain a package.

+ Similar conflicts will arise

+ if two or more people work together on a package

+ (a: "1+1=2";

+ b: "no, you're stupid; 1+1=0x0000010";

+ c: "you are both stupid, 1+1=11").

+ Most of them will probably be solved without much noise,

+ but some need a bit help.

+ There are no hard rules on how those disagreements should be solved,

+ but here are some suggestions:

+ 

+ * if two maintainers are in disagreement over a detail,

+ ask the third maintainer

+ 

+ * if no consensus can be found,

+ ask on the appropriate mailing list

+ 

+ * if still no consensus can be found,

+ ask a FESCo member to mediate

+ 

+ If co-maintainers get the impression

+ that the primary maintainer is a lame duck

+ and doesn't do their job properly,

+ they should kindly ask the primary maintainer

+ to hand over the package.

+ If they are unwilling for no good reason

+ or do not respond at all

+ or seems to be non-responsive

+ then again a mediator has to be found.

+ If there is a strong need

+ to hand over a package to somebody else

+ (packager does not respond

+ or is unwilling to find compromises on issues)

+ FESCo can do so

+ if the committee believes

+ that the co-maintainers will do the job better

+ (should not happen often).

+ 

+ [[dont_co_maintain_too_many_packages]]

+ === Do not (co-)maintain too many packages

+ 

+ There is a lot of work to do in Fedora

+ and we should try to get many contributors into the project

+ to get the work done, the load shared and Fedora improved.

+ Packaging is currently the most important

+ (maybe even nearly the only)

+ enter path

+ to get involved:

+ by doing packaging

+ people can show their knowledge and their abilities

+ before they get access to more serious stuff

+ and get respected by the key people.

+ 

+ If you have already showed that ability and gained respect

+ by properly maintaining a lot of packages,

+ it might be time

+ to slowly move on to more serious stuff.

+ One needs time for that,

+ and to get that it might be a good idea

+ to hand over some packages to other interested contributors

+ that are still on their way up.

+ That can often be easily achieved

+ by educating co-maintainers over time

+ and handing packages over to them

+ when they have shown to be doing a good job.

+ That should help new contributors finding their way

+ into the project

+ and growing up.

+ It should also share the load between the different contributors

+ which could even lead to a better overall package quality.

+ All that serves the Project as a whole and improves it.

+ 

+ This enter path might obsolete a wide area of the old sponsor process.

+ The number of software packages that are worth shipping in a repo

+ is finite.

+ We come closer to a point

+ where nearly all of the interesting stuff is packaged,

+ and thus the situation comes up

+ (or properly came up already, but we didn't notice it)

+ that new contributors cannot find

+ anything they actually use

+ that is not yet packaged

+ (we don't want new contributors

+ to package stuff they are not interested in,

+ just to get involved).

+ By giving those users a chance to get involved

+ by starting as a non-official co-maintainer

+ (e.g. an observer that provides patches),

+ then becoming an official co-maintainer

+ and eventually a real primary (per-release) maintainer,

+ we give people a chance to become involved

+ without starting with a package that gets reviewed.

+ 

+ [[other_aspects_of_co_maintainership]]

+ === Other aspects of co-maintainership

+ 

+ We had some situations

+ where maintainers had to stop maintaining packages in Fedora.

+ That can happen due to different circumstances

+ -- sicknesses,

+ accidents,

+ changes in the job or at home

+ are only some examples of reasons to stop.

+ Some of those situations happen suddenly

+ and are not foreseeable.

+ Due to this,

+ maintainers are strongly advised

+ to build a healthy maintainer community

+ around all of their packages.

+ That way, others can smoothly take over

+ even if you suddenly stop maintaining packages

+ because you won in the lottery and became millionaire.

+ 

+ SIGs cannot be co-maintainers.

+ Rather they should observe the packages

+ or make sure that the SIG members are co-maintainers where needed.

+ That

+ -- if properly used --

+ is nearly the same as having a SIG as a co-maintainer

+ and avoids people suddenly

+ getting an access to a lot of packages

+ just by joining a SIG.

+ The primary maintainer and the primary per-release maintainer roles are there

+ to make sure that

+ there is someone that actually is responsible.

+ That is quite important,

+ because letting a group of people handle a package

+ could lead to situations

+ where nobody is actually doing the work,

+ because everyone thinks that

+ one of the other maintainers will do the work.

+ 

+ Nobody can be forced to maintain packages,

+ so sometimes it might happen that

+ a package has only one maintainer.

+ That's fine,

+ but the maintainer should now and then

+ ask other contributors or interested users

+ to become co-maintainers.

+ We probably should now and then automatically send out

+ a list of packages with only one or two maintainers

+ to a mailing list,

+ so new contributors that want to get more involved

+ could easily find places where help is needed.

+ Especially packages with large numbers of open bugs

+ will need more co-maintainers

+ to try and help solve them.

+ 

+ Ask upstream developers

+ to become a co-maintainer or an observer of the package

+ -- that could benefit both sides.

+ Having upstream developers as primary maintainers

+ is often better avoided

+ (but is allowed).

+ The goals of upstream and Fedora might sometimes be too different

+ and lead to conflicts of interest.

+ (Freezes or Fedora-specific stuff are some things that

+ contributors that do not really use Fedora on their machines

+ are not aware of.)

+ 

+ 

+ [[proven_packagers]]

+ === Proven Packagers

+ 

+ Some Fedora package maintainers

+ are in the "Proven" packager group,

+ that has the ability to make changes

+ to most packages in the distribution.

+ These Proven packagers may make changes

+ to your package when the need arises.

+ This should not prevent you

+ from having co-maintainers for your packages.

+ 

+ [[current_solution]]

+ === Current solution

+ 

+ The above policy should be followed now,

+ as the infrastructure for it is pretty much in place.

+ 

+ * The general and primary-maintainers for each release

+ are typically identical

+ (exception: EPEL);

+ it is the one that listed as the devel branch maintainer

+ in packagedb.

+ 

+ * Co-maintainers typically

+ have all the same privileges

+ as the primary maintainer,

+ but may only have them

+ on their own specific branch.

+ 

+ * Ideally, all packages should have at least two co-maintainers.

+ 

+ * The package database should contain all the info

+ about maintainers and co-maintainers for each package.

+ 

+ * Co-maintainers should have the permissions to build and push updates

+ as the maintainer does.

+ 

+ === Procedure

+ 

+ The procedure is described https://fedoraproject.org/wiki/Infrastructure/WhatHappenedToPkgdb#How_do_I_give_a_user_commit_access_to_a_dist-git_repo.3F[here].