• Recommendations around Git Packaging in Debian

    From Sam Hartman@21:1/5 to All on Sat Apr 18 20:40:03 2020
    Tl;DR: This is a summary of discussion held during the summer and fall
    of 2019 surrounding Git packaging in Debian. We already had consensus
    calls and review periods, but I never got to send out a final write up.
    At the end of the recommendations is a section of help wanted items. If
    you'd like to get involved in making Git usage in Debian more uniform,
    please look at those.

    The summary/consensus call for most of recommendations starts at [1].
    However, there is an earlier consensus call [2] and some discussion of
    native packages [3].


    [1]: https://lists.debian.org/tslv9t0uj2x.fsf@suchdamage.org
    [2]: https://lists.debian.org/tsl7e70q8ks.fsf@suchdamage.org
    [3]: https://lists.debian.org/tslo909kqlx.fsf@suchdamage.org

    THE RECOMMENDATIONS

    For All Packages
    ================

    * If you host your package on a platform like salsa.debian.org that
    supports merge requests, it is recommended that you accept merge
    requests and process them. On salsa, setting your notification
    setting to 'watch' for a given repository with give you email
    notifications for incoming merge requests. It is not reasonable to
    leave merge requests enabled and ignore them; if you do not plan to
    process merge requests, disable the feature.

    * Maintainers are expected to process patches in the bts. You can
    provide merge requests as an option, but you need to still process
    patches received via the bts.

    * If your upstream uses Git, it is recommended that you use Git as the
    version control system for your packaging.

    * Using vcs-git and related fields to document where your packaging is
    found is recommended.




    Find an Existing Team
    =====================


    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.


    When There is no Team
    =====================


    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. One 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
    ========================

    This section provides recommendations for teams to consider when setting
    up their packaging practices.

    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 text is something we had consensus on back in November.
    However, in April 2019, the Salsa maintainers and nm.debian.org
    maintainers have begun making changes that addresses several of the
    concerns discussed in this section.
    ]

    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.




    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:

    * 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.

    * The area I expected to be hardest to address seems to be well under
    way to getting solved. The Salsa maintainers and maintainers of
    nm.debian.org are working on the account transition issues and may
    have a solution in place very soon.


    * Finding volunteers to propose patches to developers-reference and
    other sources.

    * We had a discussion of using native
    packages [2]. 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 you
    do work on summarizing that discussion, note that Guillem Jover
    brought up additional issues months later. Many of the issues he
    discussed overlap with issues already considered, but they should be
    included as well.


    --=-=-Content-Type: application/pgp-signature; name="signature.asc"

    -----BEGIN PGP SIGNATURE-----

    iQEzBAEBCAAdFiEE9Li3nMNy++OFgPTCQe7SUh/WssoFAl6bSQwACgkQQe7SUh/W ssq9DAf/VQUt6CtzAsAHb+Ec+dnDSfISZenY+3tAmlPKu+xuGNDCGOxsqnWFnNI5 djm+acmF3hfcyeRweqZmiccDfI0NoxdeebPFGwEgBHFHZPB7ldVbNC8HrQter+Va 4QDpNCqpzX5fWaNuOUHo2lTwy9h4jem/b2M9d2gckpvpvbjgM2MXV3iZTvujIAYS e/qTyrThsirOayJ8sQzKoASQeGTBtojKzaFxg9IqFkGJ+r1L/iMNAupRpJjlrB06 9puqCOYjfyo+fRlGyQQ9iuQy1rvHAgmydreJxqLKiHb7QxPMapPhooyM5mgWGUGE nY2QW9d6ZGqVTa+YfGSSGCCoblnAaA==s0Gw
    -----END PGP SIGNATURE-----

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)