Re: Contribution process to Publicity Team's repositories (Bits and Micronews)
Hi Charles,
Le vendredi 03 janvier 2025 à 19:34 -0300, Carlos Henrique Lima Melara a
écrit :
> Hi,
>
> Last meeting I said I would write an e-mail detailing what I had done
> in
> the Bits' repository CI/CD and more importantly why I proposed those
> changes, so here it goes - admitedly with greater delay than it should.
>
First of all, thank you for your work and for this message, and excuse me
for the delay.
> Motivation
> ==========
>
> Since I've been contributing in some way to the team (mostly Micronews
> and localization of Bits from around 2023) I saw a few things that
> would
> make the life of new contributors a bit more difficult - and also the
> lives of the reviewers too - namely:
>
> - Lack of a standard way to contribute to Bits or Micronews;
There are two pages dedicated to explaining how to contribute:
https://micronews.debian.org/pages/contribute.html
https://wiki.debian.org/Teams/Publicity/bits.debian.org
> - Lack of a standard review process;
Sure we must get into the habit of submitting Bits and micronews posts to
the Publicity team for review, according to an explicit protocol.
> - Needing to install all dependencies locally to build/test things.
Surely for occasional contributors but is it necessary for regular
contributors (and at least for team delegates who are responsible for
putting posts online).
>
> This last topic is specially more important for potential new
> contributors that do not have a lot of experience with Debian and other
> GNU/Linux OSes. Think people that like press/publicity stuff but have
> used windows most of their lives.
I don't think there are many potential contributors who would like to
publish on official Debian resources who don't know Linux or Debian.
>
> What has been done?
> ===================
>
> Ok, these were the problems I wanted to solve, or at least mitigate a
> bit. My first attempt was making use of our Salsa's CI/CD capabilities
> to lint the markdown of the repo. Then, I thought, it would be nice if
> it could build the website and show us the outcome so it would be
> easier
> for newcomers and reviewers. It was nice, but one still would need to
> go browse the artifacts and select the correct file to display the
> page.
> Thankfully, we can host web pages easily with Gitlab Pages and it's
> easy
> enough to setup for the default branch and so I did for the master
> branch of the bits repo.
>
> Side but kinda important note, would guys be ok if we start to
> think about moving our default branches to main instead of master?
> I think it would require some planning so I just wanted to start the
> discussion.
Why not, if it doesn't take too much time and energy to do it and if, as
joost says, there is a detailed instruction "to keep my local checkouts
working."
>
> So what do we have now?
> =======================
>
> On every push to Bits default branch the CI is started and:
>
> 1. Run markdownlint on .md files and halt the pipeline if there is an
> error so it doesn't go to the build step (we can change this
> behaviour to allow it to continue). The rationale is to not waste
> computing resources building the website if one is probably sending
> a
> following commit fixing the markdown.
If the process stops at this stage, it means that the contributor must
know how to correct the errors reported by markdownlint, otherwise he is
blocked and cannot send the post to salsa for the team to review. I
prefer that we can access event the faulty texts.
>
> 2. Build the website with pelican in the same way it's built for
> publishing on bits.debian.org (well, I'm actually assuming the
> commands in the makefile are the ones used officialy).
>
> - The artifacts of the build job has all the HTML generated pages
> and
> can be browsed via salsa's web interface.
>
> 3. Publish the resulting content on gitlab pages so one can view the
> result in [1]. Note that this doesn't change anything on [2], it's
> only a staging place where we can see the state of the tip of the
> git
> repo.
+1 But I always build the post locally before pushing them to salsa (and
now I also installed markdownlint and plan to use it systematically.)
>
> - **This step only runs if it's the default branch.**
>
> [1] https://publicity-team.pages.debian.net/bits
> [2] https://bits.debian.org
>
> Cool, so what do we accomplish here?
> ====================================
>
> I think it makes the lives of Publicity Team delegates easier when
> reviewing the work of people with commit access to the bits repo. For
> instance, if I (take I as a general person who has already contributed
> and has access to the bits repo) want to write a bits post, I can do it
> and push to salsa. Then I can ask one of the official members to review
> and publish. This person than can simply go to [1] and check the work,
> no need to update a local git copy and build the website.
>
As a precaution, I would advise always sending posts with draft status so
each submission must be subject to this status change before publication
and (for me) it is often easier to prepare commits locally with my usual
editor rather than with the salsa interface (for example to check
trailing or double spaces, line length or spelling correction)
> What about for people without commit access (a.k.a. new contributors)?
> ======================================================================
>
> If they fork the project and work on the default branch, they have the
> same benefits. They could write the markdown file, commit and push to
> their fork. Then the pipeline would do the same as it does for our
> official repo and publish the fork's content under
> <salsa-username>.pages.debian.net/bits and they wouldn't need to build
> locally nor install all dependencies.
>
> * Obviusly I think it would be very important to build locally before
> commiting and opening a Merge Request, but I'm thinking on the
> average
> newcomer to GNU/Linux in general here.
I believe that the best we have to do is to encourage newcomers to submit
posts for bits and for Micronews on the debian-publicity list. This is
the best way to create interactions with them and to help them progress
and gradually integrate into the team.
>
> What's left?
> ============
>
> 1. Obviously document how one can contribute to the repo.
>
> I'm thinking in adding a CONTRIBUTING.md file and mentioning it on
> the readme. What do you guys think?
>
The links above can be used as a basis as well as the following pages
https://salsa.debian.org/publicity-team/bits/-/blob/master/README.md?ref_type=heads
https://salsa.debian.org/publicity-team/micronews/-/blob/master/README.md?ref_type=heads
> 2. Extend this to the Micronews repo. Working in the exactly same way
> as
> the Bits repo.
I tried markdownlint on some micronews : it points to line lengths but
the script automatically creates long lines. And it would be a shame to
modify this script which works wonderfully well...
And as a committer I never had a build problem. So as the French saying
goes, the best is the enemy of the good...
Just perhaps we should recall the problems with the apostrophe and
quotation mark characters or the rule for the URLs.
Most if not all the micronews are created and sent to Salsa directly from
a terminal without going through the interface. What feedback can there
be in the event of a construction failure?
>
> I think there it would be even better for attracting new
> contributors
> because it's way easier to create a micronews than a bits post.
And as I said before, the best way for the newcomers is to send the
micronews draft to the publicity list... The irc channel is also a good
place but not everyone is connected to it all the time and the list
allows for convenient archiving.
>
> 3. We could extend the CI to also do more stuff e.g. spell checking.
Why not but, I usually use my regular spell check before sending posts...
and I ask for review :-)
And as an old man, I remember the rules that used to be in Linux: one
task, one tool :-(
>
> Not sure about this one, but I'm open to feedback.
>
> What now?
> =========
>
> Well, thanks for reading this far :-) The whole point of this e-mail is
> to put everyone on the same page and ask for feedback. Should I
> continue
> to implement points 1 and 2 above? Any feedback or ideas on point 3?
> Should I nuke everything?
The point 1 must take priority.
>
> We can discuss via mail or put as a topic for the next meeting,
> whatever
> you think is best.
I think we can go on to discuss via email particularly on the choice of
the blocking nature of the process, and prepare the explanation pages for
users.
>
> Cheers,
> Charles
Thank you again for your useful work
Jean-Pierre
Reply to: