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.
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;
- Lack of a standard review process;
- Needing to install all dependencies locally to build/test things.
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.
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.
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.
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.
- **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.
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.
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?
2. Extend this to the Micronews repo. Working in the exactly same way as
the Bits repo.
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.
3. We could extend the CI to also do more stuff e.g. spell checking.
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?
We can discuss via mail or put as a topic for the next meeting, whatever
you think is best.
Cheers,
Charles
Attachment:
signature.asc
Description: PGP signature