This is a summary of discussions we had in August and September around how we want to use salsa. Presented so those involved in the discussion can see if I'm calling consensus correctly and as a last opportunity for others to comment. A few tweaks from my original proposed recommendations. If you were OK with that version you can likely skip this entirely, although I'd appreciate it if you'd search for "HOW YOU CAN HELP" and glance at that section at least.
This message focuses on the areas of the original recommendation that received significant comment and includes the current recommendation at the end. As a reminder, this recommendation is purely optional; it is intended to help those looking for best practices or newcomers searching for a recommendation. If it doesn't fit your needs, then find something that does. Discussion Comments ==================== Teams ***** We were reminded at several points that the best practice is to find a team and to maintain your package using their practices. That was always the intent, but I'm proposing to update and clarify this from the top just to be extra clear. Debian Group When no Specific Team ********************************** TL; DR: I think there is consensus behind recommending the Debian group on Salsa when there is not an existing team to use. This consensus is not complete; some disagreed. If after reading the summary people want to have a quick vote, I think that would be fine. In more detail: I proposed that the debian group would be a sensible default if there is not a team project to use. We had a wide ranging discussion. There are two big concerns with the debian group. Technically, any DD has push access to any repository in the group. Also, as Ansgar pointed out, the wiki page [1] says that it is reasonable to commit with no prior discussion. [1]: https://wiki.debian.org/Salsa/Doc#Collaborative_Maintenance:_.22Debian.22_group My original text implied that the Debian group was a lot closer to low-threshhold NMUs than a complete free-for-all. In practice, I think that's true: I think that the actual social conventions that get used in practice are more conservative than the permissions granted technically and by that wiki page. Russ agreed that Debian is a sensible default [2]. Enrico agreed. After re-reading the proposal, Jonas agreed that this was a reasonable recommendation. He would not have supported something stronger like a policy which limited maintainers' flexibility when this recommendation does not meet their needs. [2]: https://lists.debian.org/msgid-search/875zm0or60....@hope.eyrie.org Ian Jackson thought that recommending the debian group would be reasonable if we did three things: * Document which maintainer branch format a maintainer is using * Update documentation on when it is reasonable to push to the debian group * document the above David Bremner is uncomfortable with the idea of having all DDs have push access to thousands of packages. He doesn't think we have the social conventions for that. However he said he would be OK with the recommendation if we did as Ian proposed (documenting branch format, documenting when to push). Ansgar argued that documenting the branch format is unnecessary given all the work you need to do to contribute to a package. Several disagreed arguing that it helped them do their work. Bernd Zeimetz argued we didn't need a recommendation. We could just list places people could host with advantages and disadvantages. Matt Zagrabelny and Enrico argued that having specific recommendations lowered the bar to contributing because you did not need to evaluate the advantages and disadvantages for your environment. This is consistent with feedback we received during the dh discussion and during the DPL campaign. (Enrico's message was posted to a related thread on -project, not to debian-devel) Ansgar argued that a recommendation could be harmful because we take a long time to update documentation/recommendations and it would get out of date. Several people pointed out that under that argument we wouldn't have documentation at all. Even if the slope is not that slippery, the arguments about lowering the bar to entry apply here too. However having the recommendation become out of date remains a residual risk. Scott Kitterman is concerned that we are loosening the boundaries of individual responsibility around what it means to be a maintainer too far. He's concerned that if we weaken the maintainer model too much, that everyone will have responsibility. He believes that is the same as no one having responsibility. It became clear in the discussion that the alternative to the debian group is repositories hosted under individual salsa accounts. The debian group is widely used today. It certainly dominates any individual salsa account. It also dominates (at least in terms of vcs-git in unstable) individual (non-team) accounts combined. There are some teams that are bigger than the debian group. Since we recommend team package maintenance, that's great to hear. (I posted some stats on the thread. People argued over my methodology and choice of stats, but in any interpretation proposed, the debian group is significant and dominates individual accounts). Conclusiony Thing ----------------- * Make it clear that team packaging is preferred; emphasize that more. * If you are using debian group you should document your branch format. Update to say that. * It would be valuable to better understand what social conventions have evolved around pushing to debian. These should be documented even if there is not a formal change to the rules around pushing. I disagree with Ian Jackson and David Bremner that we need to block a general recommendation on what may be a somewhat involved project of documenting that social convention. I think it is great work. I think this recommendation will be far more valuable when it completes. A lot of people are using the debian group today successfully with few complaints even though that work hasn't been done. So I don't think a compelling argument for blocking a recommendation on better understanding social conventions has been made. * I believe that there is a rough consensus in favor of the recommendation. In judging consensus I'm presuming a strong consensus behind having recommendations in this space; I'm giving a lot of weight to the lowering barriers to entry argument. I'm also giving significant weight to the debian group being up and operational and used by a lot of people. Yes that's partially because it was recommended as part of the Alioth migration. I don't see that counting against anything. But this consensus is still kind of rough. If people believe I've made the wrong call here, I think it's entirely reasonable to hold a GR and understand the view of the project today. * It's clear there is no consensus in favor of alternatives. For example there is not a consensus in favor of saying that best practice is to put packages in individual accounts. That's a reasonable thing to do, but we don't have consensus in favor of that being the best practice. So, this is a question between debian group and no recommendation at all. Github and Non-Free Services **************************** too much has been written on this already. There is no consensus to forbid using Github. More discussion on this topic will not serve the project at this time. The recommendation against using Github appears to be relatively uncontroversial. Some disagree, but I call the consensus in favor of retaining that. Salsa CI ******** The salsa admins wrote and let us know that right now we don't have enough resources on Salsa to recommend the Salsa CI pipeline for all projects. So I'm removing that recommendation. A couple people disagreed with this and argued that I should include the recommendation even over the Salsa Admins' objection. Part of giving people responsibility is letting them make choices over what they are ready to support. The project can let the Salsa Admins know that we as a community want stronger support for Salsa CI. We can work with them. They can ask for more help if they need it. Eventually, we can evaluate whether the people running a service are doing what the project needs. But while they have that responsibility, they need our support. And that means they get to decide when they are not ready for something. It seems clear that a lot of people want to see Salsa CI support improve and I think it's reasonable for us to ask for periodic feedback both from the Salsa Admins and the Salsa CI team on how that is going. Changes from Previous Version ***************************** * Add Existing Team first * Non-DDs should ask for a debian group repo or use personal namespace. * For merge requests, note that you should be as responsive as BTS if you enable merge requests at all. * remove Salsa CI recommendation:-( * Do not make a recommendation for VCS technology if the upstream is not in git. Ian Jackson gave compelling arguments why there's no clear consensus in this case. AND NOW THE Recommendation HOW YOU CAN HELP =============== There are a number of tasks where we need help to make these recommendations more useful. Help would be appreciated in the following areas. If you are willing to take on tasks please write back and let us know: * Exploring what current social conventions are around pushing to other people's repositories in the debian group on salsa and documenting them. This is more about documenting what people do than about documenting what permissions people have. * We've talked a number of times about how it would be great to do a better job of documenting what branch format (patches unapplied, patches applied, dpm, packaging only, etc) a repository uses. It would be great if someone would work on figuring out how to document that. It would be even better if someone would work with tool authors like the authors of git-buildpackage, dgit, debcherry, etc and see if there are ways these tools could automatically maintain this information. This is an area where cross-tool coordination could make all our lives easier. * In the "Account Transition" section, I talk about some of the issues that can come up as people become DDs, retire, or otherwise have their account change. It would be very helpful to get someone to consider these issues and figure out what if any changes are needed. That probably involves working with Salsa Admin, DSA, and NM among others. * Once we get done here we'll need people to help fold this in to developer's reference or other appropriate documentation sources. I'm not going to have time to do that. * Not quite related to this round. We had a discussion of using native packages. My conclusion from that is that there are a lot of issues to consider when choosing to use a native format but that sometimes it is a reasonable choice. It would be really helpful to get all the issues people brought up in that discussion onto a wiki page into a non-judgmental way. I think using native formats will always be somewhat advanced, but I know I'd benefit from the wiki page. If no one else gets to this I'll get there in a few months probably. Existing Teams ============== If there is an existing packaging team that your package fits into, join that team and package it there. Use their recommended Git packaging practices. See the Team Recommendation below if you are setting up a new team. General Recommendation ====================== This recommendation is intended for people who are simply looking for an approach that will work well with approaches others are using. If you are packaging something in a large team, follow their existing practices. If you are setting up a new team, see the recommendation for teams. If you have your own ideas about what you'd like to do and choose to disregard this recommendation, that is also fine. If you do not already know the answer you want, this recommendation is for you. If you are a Debian Developer packaging a package for inclusion in Debian, you should store your packaging information in one repository per package on salsa.debian.org in the debian group. That is you should create a repository under https://salsa.debian.org/debian . You should make sure that at least one person sets their notification level to 'watch' rather than global. This way you will receive notifications of merge requests and changes. Hopefully you will choose to monitor merge requests for your repository. If not, turn off merge requests. If you enable merge requests, you should be as responsive to merge requests as you are patches in the BTS. You should document the branch format (such as patches unapplied (gbp pq)) that your repository uses. Best practice for documenting this is still evolving. The best current option is to document your branch format in debian/README.source. Alternatively if you use `dgit push-source`, your source format is documented in maintainer tags. If you are not a Debian Developer, you cannot directly create a repository in the debian group. If you're willing to wait for a Debian Developer to create a repository for you and grant you access, do that. If that wait would be long enough to frustrate you or demotivate you, you should create a repository in a your personal namespace on salsa.debian.org and store your package there. By creating a repository in the debian group, you grant access to all developers. That way people performing NMUs can directly commit their changes. It will also make it easier if you later orphan the package to preserve version control history, URIs and merge request history. Notes and Limitations --------------------- The debian group is great for relatively unrelated packages. It may not be appropriate for a large number of related packages (especially when maintained by a team) for these reasons: * It is hard to examine the group of related packages without also seeing other unrelated packages * You cannot subscribe to watch a group of related packages with one click * Access to people who are not Debian Developers needs to be granted on a per-repository basis in the debian group Some teams with a large number of packages have adopted a monolithic format where a single repository contains information for many packages. It is not the intent of this recommendation to judge that approach either positively or negatively; this recommendation is targeted at a very different audience. This recommendation is not appropriate in cases when Debian Developers should not have push access to the repository. For example if you are mirroring the repository from another service and do not want changes pushed to this replica, using the debian group is inappropriate. Two-way mirroring is desired when possible. Packages not on Salsa ===================== Some people choose not to host their packages on Salsa for a variety of reasons. Examples include wanting to host Debian packaging in the same repository as upstream development when the Debian and upstream maintainers are related. Even if you do not host your packaging work on Salsa you should: * Host your packaging work in Git assuming that the upstream does not use some other version control system. There is no recommendation when upstream uses different version control. There are advantages to using Git as well as advantages to using what the upstream chooses. * Use a public repository where in-progress and ongoing work are available to the public. Do not just push when you release. * Set the vcs-git and vcs-browser fields in debian/control to point to your repository. * Document the maintainer branch format you use. You are encouraged to mirror your repository to Salsa so that people can find more of the Debian packaging in one place. Non-Free Services ----------------- It is important to many members of our community that they be able to do work within Debian without using non-free software or web services that depend on non-free software. Github is a common example of a web service that uses non-free software. Clearly community members can use the BTS, make NMUs and interact with mailing lists. However, not being able to interact with packaging Git repos can significantly reduce developer's effectiveness. Evaluate the impact on our community before using a non-free service like Github for Debian packaging. Would your needs be met by mirroring from free services to non-free services? Using non-free services for Debian packaging is not recommended but is permitted. Some have suggested that we forbid the use of non-free services for Debian packaging. First, we'd rather public git repositories be available than for example have people claim they are not using VCS at all. Secondly, we don't even have a mechanism to codify such a policy, nor is it clear that it would be desirable to have formal policy for what tools people use prior to upload. If the use of a non-free service is preventing an active member of our community from contributing to a team, the team should work to find a solution so that member can contribute effectively. Recommendation for Teams ======================== The debian group on Salsa may not be the best choice for teams maintaining a large number of packages. The team packages will be mixed together with other packages and that may be confusing. Often, a team will want their own group to segregate their packages. In this case the team should create a team group on Salsa and store their packages there. This will make looking at changes to these packages, merge requests for the set of packages, and CI information easier. It is not possible to grant the debian group access to all packages in a group at once. However, if a team wishes, they may grant push access to the debian group on a package-by-package basis. Best practice is for multiple people to have owner privileges on the team. If the team owner leaves Debian, having a second team owner will make managing the team easier. Similarly if an account is locked for security reasons, having a second owner will make the transition smoother. Account Transitions =================== This isn't so much a case where we have a recommendation as where it seems like we need to do more work. There are some awkward issues around Salsa accounts: * When you retire from Debian or are removed, your salsa account becomes inaccessible. That means you no longer have access to teams and repos that you are granted access to. * Granting access to repositories in personal namespace becomes problematic. You will typically no longer be able to push to repositories in your personal namespace. * If you are the only active team owner for a team, gaining access to the team will require administrator action and will be relatively slow. * You will need to regain access to any repositories that you should have access to. Depending on why an account is locked, the above may be strongly desired or deeply frustrating. There's been enough discussion of this issue that it seems like someone should take on the task of trying to figure out what we as a project want. Solutions might include: * Procedures that get followed when accounts are closed. We probably don't want more effort added to the tasks of NM front desk, MIA or DAM. But if additional volunteers stepped forward who wanted to help with these transitions, it might make sense to approach things that way. * Changing how Salsa and Debian LDAP interact. This would involve figuring out what we want and working with the Salsa admins and DSA.
signature.asc
Description: PGP signature
