On january 17th 2019, as a fresh newcomer in the group, I (Cyrille) proposed to try and improve the Debian Perl Group's websites (ie: wiki and homepage) to the mailing-list (see https://lists.debian.org/debian-perl/2019/01/msg00026.html).
The feedback was quite positive and some discussion started on the mailing list.
Since it's hard to keep track of all the opinions and decisions taken within the mailing list, I've created this page to try and keep these centralised and easily accessible.
This page is a work in progess.
Improve documentation (organisation, content, presentation,...) to:
- Better support newcomers who make their first contribution, co-maintaining packages with the Debian Perl Group (DPG).
- Allow existing maintainer to easily find relevant informations for their day-to-day activities.
Main issues identified
The following main issues have been identified as impending swift inital contributions by newcomers:
This wiki and the DPG's homepage have somewhat redundant and conflicting informations;
- Some information displayed on this wiki and the DPG's homepage is in fact maintained as POD docs in DPG's tooling (e.g. pkg-perl-tools). As a result, these informations on this wiki and the homepage may be obsolete;
- Some duplicate or even contradicting information has accumulated in the wiki and on the website.
The following strategy is proposed to reach these goals:
- Better segregate the purpose and content of this wiki and the homepage: This wiki should be targeted for quick edits, task lists, "scratch pads", TODO lists,... while the homepage should be intended for more static, generic, and "official" information;
- Automate the synchronisation of information displayed on the homepage whose authoritative source is the DPG's tooling;
- Manual cleaning.
Though nothing is ever set in stone here, it often helps to write things down to ensure the best common understanding possible.
With this in mind, I believe the following decisions have been made:
- The strategy is agreed;
The inital proposal that I sent on the mailing list (https://lists.debian.org/debian-perl/2019/01/msg00051.html, see attachements) is taken as basis for discussion for implementing the strategy;
- TODO: The welcome pages shall be moved on the team's website.
- TODO: In the inital proposal (decision 2), enhance the text linking to the homepage a little so people know what kind of references they can find there (goals,contact, policies, howtos, talks, etc).
TODO: change the https://packages.debian.org/sid/dh-make-perl link to the man page of dh-make-perl (https://manpages.debian.org/stretch/dh-make-perl/dh-make-perl.1p.en.html)
TODO: Add a link to the manpage of dpt (https://manpages.debian.org/stretch/pkg-perl-tools/dpt.1.en.html)
The following discussions are in progress (lists are to be read in chronological order from oldest (top of the list) to newest (bottom of the list)):
Should we still reference PET?
- PET is broken (and might never be back?) [update: PET is gone]
Alex says: Many of the PET information and features have been integrades into tracker.debian.org, e.g. https://tracker.debian.org/teams/pkg-perl/
- Gregor agrees
There seems to be a misunderstanding about my original intent: I have no intent to delete the https://perl-team.pages.debian.net/changelog.html all together, but rather to update it to remove reference to PET.
Lucas notes that "we don't track these keywords (ndlr: those found in the changelog page) in d/changelog yet"
I propose to investigate how hard it would be to replace PET by https://tracker.debian.org/teams/pkg-perl/ in our docs.
Is https://perl-team.pages.debian.net/qa/ still used?
- I was asking this question because it doesn't seem to contain anything
- Gregor thinks "the current qa/ directory with its cruft can be removed."
- Alex says that "Tracking those issues is still an interesting thing to do IMHO, though we may need to find a different place for that."
- I propose to try to find back the scripts that should generate this info and see if they can/need to be updated
What's the purpose of pkg-perl-tools?
- I was asking because it seems important and I did not find any documentation about it.
Both Alex and Gregor seem to answer that adding a link to the man page of dpt would be good [or the the package description at https://packages.debian.org/sid/pkg-perl-tools or https://salsa.debian.org/perl-team/modules/packages/pkg-perl-tools/blob/master/debian/control ; but https://manpages.debian.org/unstable/pkg-perl-tools/dpt.1.en.html is also nice, just that pkg-perl-tools is more than dpt(1)]
What's the purpose of this link: "Debian Perl Group on Launchpad "
- I don't understand how to use it
- Alex replied that it helps keeping "track of bugs reported in Ubuntu thay may be interesting to deal with in Debian too (e.g. if there's something wrong with our packaging)."
- I've looked further at the Debian Perl Group on Launchpad, but there doesn't seem to be any activity in there except a mailing list. This mailing list is specificaly mentioned on the wiki, so maybe this mailing list is the sole reason of this link?
- I would like some more information how this "Debian Perl Group on Launchpad" is used. [to track bug reports in ubuntu against our packages]
Other issues you might have with the Wiki or the homepage can be listed here, they will be considered, and, eventually moved to the "open discussion paragraph", and then, finaly, to the "Decisions" paragraph:
sbuild documentation: While looking for documentation related to sbuild, I saw similar information located elsewhere (eg: https://wiki.debian.org/sbuild). we should consolidate
https://www.debian.org/doc/devel-manuals: This page seems *the* reference for DD and DD-wannabe. We should add a link to this page on the homepage