Looking for additional Qubes Documentation Maintainer

[Marek Marczykowski-Górecki]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

Hi,

We are looking for an additional documentation maintainer to help Unman
- - the current doc maintainer - with the task. The role mainly consists
of reviewing and merging pull requests to the documentation, but
sometimes it's also about writing/adjusting some parts. The person
should be familiar with Qubes OS enough to be able to verify accuracy of
proposed changes, but they don't need to know everything - it's okay to
ask others in case of doubt. The important part is knowing when to ask :)
Technically, it involves working with git (including signed tags),
markdown files, and (hopefully very soon) reStructuredText (rst) format
and Sphinx.

Since the role includes push access to the qubes-doc repository, we
expect this to be a person, that has already been participating in the
community for a significant time[1].

We understand the value of well-maintained documentation, and to help keep
it sustainable we can provide some remuneration for the maintainer from the
funds we collect on OpenCollective.

If you think you will be a good fit for this role, and would like to
help the project, let us know.

[1] lets say, 3 years, to put the bar higher than xz-utils ;)

- --
Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
-----BEGIN PGP SIGNATURE-----

iQEzBAEBCAAdFiEEhrpukzGPukRmQqkK24/THMrX1ywFAmdJt2sACgkQ24/THMrX
1ywy2Qf+IQjbj+/Et8AxTWcB4yUNNUtSGDhQlLS6rbEVLXAV0spiAG2MIGQcguQI
ir6YM77T0HjVYQeXGa0eKSYlG5CUc9wqdbasaSiH6o804oMfLTqJrhhHMQNibpiw
2aYNJp2wWRQ1OlWvCXg7gaIZmKDgiNcpydVPITZiWE17BHPgGvoWrEp3IeXCvfip
jFu+JdHcqFcmIOIt3WDrKz/TA9WZznulJ8HcZRCJRBrqR6jOzaP+sT0DdjgFRhUq
mQo98aWfHnBh0W8UmewAgQ6sITa81gty1y12+ZsDksYYSOMraYwrv0V7HIKnUAB9
n5X6boxKrTpFrjBvWA5jA1pvbGH9AQ==
=Wh8M
-----END PGP SIGNATURE-----

[Ben Grande]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On 24-11-29, Marek Marczykowski-Górecki wrote:
> Hi,
>
> We are looking for an additional documentation maintainer to help Unman
> - the current doc maintainer - with the task. The role mainly consists
> of reviewing and merging pull requests to the documentation, but
> sometimes it's also about writing/adjusting some parts. The person
> should be familiar with Qubes OS enough to be able to verify accuracy of
> proposed changes, but they don't need to know everything - it's okay to
> ask others in case of doubt. The important part is knowing when to ask :)
> Technically, it involves working with git (including signed tags),
> markdown files, and (hopefully very soon) reStructuredText (rst) format
> and Sphinx.

Hi,

Given that all of the maintainers have been from Core, requiring for the
first months approval of a Core team member would be safer. I understand
that this may rollback to Core team doesn't even having time to do a
brief review and mark PR approved, just an idea...

> Since the role includes push access to the qubes-doc repository, we
> expect this to be a person, that has already been participating in the
> community for a significant time[1].
>
> We understand the value of well-maintained documentation, and to help keep
> it sustainable we can provide some remuneration for the maintainer from the
> funds we collect on OpenCollective.
>
> If you think you will be a good fit for this role, and would like to
> help the project, let us know.

I believe to be good fit for this role as I value well written
documentation, I have contributed to many Qubes repos before, but most
contributions were not docs related. My disadvantage is I am not a
native English speaker and sometimes I commit grammar mistakes.

> [1] lets say, 3 years, to put the bar higher than xz-utils ;)

I have not participated in the Qubes community for 3 years. I don't even
have 3 years as a user, although I hope, if accepted, to provide
meaningful value to the state of the documetantion, as I consider myself
"well-versed" in the Qubes environment.

As there will possibly be only one more maintainer, if another person is
chosen, I make myself available to help answer questions about Qubes OS
that a co-maintainer might have.

- --
Benjamin Grande
-----BEGIN PGP SIGNATURE-----

iHUEARYIAB0WIQRklnEdsUUe50UmvUUbcxS/DMyWhwUCZ078jQAKCRAbcxS/DMyW
hx20AP9SaeTxJQ+FcEzF8gcz6+Fnd4LcnEvhH/Vd1V+rQYhi2wEApFC/4aHrMWcV
aDAOPMIWJ6RpwzsDytEfKso/ABfqfg4=
=Zaaw
-----END PGP SIGNATURE-----

[Marek Marczykowski-Górecki]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

On Fri, Nov 29, 2024 at 01:45:34PM +0100, Marek Marczykowski-Górecki wrote:
> Hi,
>
> We are looking for an additional documentation maintainer to help Unman
> - the current doc maintainer - with the task. The role mainly consists
> of reviewing and merging pull requests to the documentation, but
> sometimes it's also about writing/adjusting some parts. The person
> should be familiar with Qubes OS enough to be able to verify accuracy of
> proposed changes, but they don't need to know everything - it's okay to
> ask others in case of doubt. The important part is knowing when to ask :)
> Technically, it involves working with git (including signed tags),
> markdown files, and (hopefully very soon) reStructuredText (rst) format
> and Sphinx.
>
> Since the role includes push access to the qubes-doc repository, we
> expect this to be a person, that has already been participating in the
> community for a significant time[1].
>
> We understand the value of well-maintained documentation, and to help keep
> it sustainable we can provide some remuneration for the maintainer from the
> funds we collect on OpenCollective.
>
> If you think you will be a good fit for this role, and would like to
> help the project, let us know.

Thank you all who volunteered! We have received many more candidates
than we could hoped for, and it was not an easy decision to make.
After evaluating all the submissions, we still couldn't decided on one
person, so in the end we selected two additional maintainers:

1. Solène Rapenne (https://github.com/rapenne-s). She is an excellent
technical writer, earlier in the OpenBSD community, now in our. She isn't
here very long, but it's clear she is a reliable and trustworthy person
based on her past FOSS contributions.

2. m (https://github.com/maiska). She is contributing to Qubes OS's
documentation for a long time, mostly on the infrastructural level
(markdown files organization, adding language tags, Transifex
integration and many more). She also spent a lot of time preparing
migration to Sphinx / Read the Docs and knows a lot about all the tools
involved. On a more personal note, we have met in person on several
occasions, she is definitely a real person ;)

I hope two additional documentation maintainers will allow us to move
forward with the documentation :)

- --
Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
-----BEGIN PGP SIGNATURE-----

iQEzBAEBCAAdFiEEhrpukzGPukRmQqkK24/THMrX1ywFAmdV/CMACgkQ24/THMrX
1yzilwf9F5aBL0XtP7nZEGGmdqVwLFJf7Aa4Slu0+/RFvVbJF0cfGXOD2ARpCMDq
OkaXKAuwQuNcFVDXt7oM/5XAQmaS8GlQ0c1fDZz+mvbfznUaDFpnHi0G19iR8mdl
r+stQG1Te2vaLxO+Bw0D/ayzuKMccqXqelpY8OEeMwB5xctzxdehjOpYBbKFJUwu
qoanD98ox/dia/ubBltd0qoQq1RBIMqcjOXi1fwKIkKCkCV28OcfJpJ8sf6doB3C
FcwnRlbnNHIpNXDMEdj75TvpZQkyvT7o1yab8Xi/Z24GjPtkW5duPpD46743VJfp
mKSFk7/2aTviyIrwWZpY9l7aBBfsgw==
=6dik
-----END PGP SIGNATURE-----

[Marek Marczykowski-Górecki]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA256

And here is a bit of instructions how things work. M knows most of this
already, but for completeness I'll write it anyway.

It's a bit chaotic... but maybe it would be good to put that somewhere
into the documentation? ;)

But also, some of this is going to change with readthedocs migration.

## Repositories and branches

There are 5 repositories:
1. qubesos.github.io - this is the main website repo. It has the other
four connected via git submodules. This repository is hosted via github
pages on www.qubes-os.org.
2. qubes-doc - this is the main documentation repo
3. qubes-attachment - extra files for docs (images etc)
4. qubes-posts - this is news/blog repo
5. qubes-hcl - hardware compatibility list

You've got write access to qubes-doc, qubes-attachment and qubes-hcl
(but that last one is least relevant for you for now).

Now the important part: all pushes to the main/master branch on those
repositories must have a signed tag on top. This means all the merges
needs to be done locally via git command, _not_ via github's green
button. There is a bot that verifies if new content has authorized
signature on top, and if so, it updates relevant submodules in
qubesos.github.io repo. The actual script is in _utils/update-submodules
in that repo, it's also useful to update your local clone with one
command that will verify relevant signatures.
You can also find helpful git settings at
https://www.qubes-os.org/doc/code-signing/#using-pgp-with-git

All the repositories have both "main" and "master" branch. There is a
bot that synchronizes them. Do not push to both manually, if you manage
to do that, it may require manual intervention to fix things up.

Force pushes are blocked for all of those repositories to both main and
master branches.

## Pull requests and reviews

Generally, changes should go through pull requests, even if you are
going to merge them yourself - at the very least to give CI a go. But
this is not enforced, and it's okay to skip PR for _really_ trivial
changes.

Since generally we try to not trust infrastructure too much, review
should be done locally, and then post relevant comment in github's web
interface. There is a helpful trick to fetch pull requests:

git config --add remote.origin.fetch "+refs/pull/*/head:refs/remotes/origin/pr/*"

Now, when you do `git fetch origin`, you will also get refs like
origin/pr/123 with PR#123 content. Then you can review that (git diff,
git checkout etc).
If all is okay and you are going to merge directly, you can
do that right away. If you want to request some changes, just click that
through github's web interface. But there may be also cases where you
want to approve changes but not merge them yet for any reason. Here, we
have a helpful tool that posts a signed comment saying which commit
specifically you approve (so, github can't lie about what content got
approved):

_utils/review-ok origin/pr/123

Optionally with a message in the second argument (remember about quotes,
and don't try fancy formatting - the script is stupid and will likely
choke on it).
For this to work, you need to put github API token into `~/.config/hub`,
in a syntax used by the "hub" tool. For example:

github.com:
- user: marmarek
oauth_token: ghp_...
protocol: https

There is also second tool - _utils/review-verify that helps verifying
such comment.

## CI

All of the repositories have CI connected. When a PR is made, it takes
it to a temporary branch, merges to master (so it always runs on what
will end up in the final repository) and tries to build the website. If
build succeeds, then it runs a spellchecker. To avoid manually building
a dictionary with specific technical terms, it compares "bad" words with
previous state (what is in the main branch). And it complains only about
new "bad" words. If some reported spelling mistake is in fact false
positive, simply merge that PR anyway, and it won't complain about that
word next time.

There are two+ useful commands you can use:

- - PipelineRetry - retry the CI build, including refreshing the temporary
branch with the new content from the main branch
- - testDeploy - take most recent CI build and deploy to
wwwpreview.qubes-os.org. It overrides whatever was deployed there
before.

To execute a command, simply post it as a comment (as the only word in
the comment). Only some users are allowed to execute them - you both
are.
The second command works only when the CI build completes (you need to
wait for that before posting the command). The website build must
succeed, but it will still work if the spellchecker failed.

There is a bit more about that here:
https://www.qubes-os.org/doc/continuous-integration/

### ReadTheDocs migration

There is a lot to be said here, and several of the above points will get
outdated. But as for the impact on the repositories layout, the current
plan is:

1. Merge qubes-attachment repo into qubes-doc - at least as far as
documentation-related files goes, other files may stay in
qubes-attachment repo for now. That separation is mostly historic
artefact, from the times we used Trac... and is quite
inconvenient/confusing without clear benefit.
2. Convert all the documentation into rst format, more or less in a
single commit (this enables git, in some cases, to treat this conversion
as rename with changes, and nicely follow the file history).
3. Publish the qubes-doc repository on readthedocs, on a nice domain
like doc.qubes-os.org (exact name TBD).
4. Disconnect qubes-doc from qubesos.github.io and replace _doc former
submodule with a directory full of redirects to the new location of each
doc page.

You can see step 2 at https://github.com/QubesOS/qubes-doc/pull/1367
And step 4 at https://github.com/QubesOS/qubesos.github.io/pull/243
Both of the above PRs are outdated, but M has more up to date content
somewhere on her repository.

- --
Best Regards,
Marek Marczykowski-Górecki
Invisible Things Lab
-----BEGIN PGP SIGNATURE-----

iQEzBAEBCAAdFiEEhrpukzGPukRmQqkK24/THMrX1ywFAmdflBcACgkQ24/THMrX
1yz29wf/dkvwTkjBCi+OxhZbQB4LdMS7RmFtFSXDEtlG7dZ0J9EuBadFjeq8ZCaS
BKpEDKc9gFsDT33wTg7eRWOuqaOt2AAGkxwBGX95EIufLqNrAgsYo7zLvZXeYVnr
5rnmlfGXqPzgN+Y7A/V9pFTQOsJ+gH1eXMdnHDJ5cG0+1K/kS6SKYw2H2/WdJBSh
us/tX9NS644w5PSqQntkQ6RdiCCjqufgvnryATczfw68Y54mOYbw70IWanW3lpqa
5+99KsZbdTxuIkUZGWrwcZN4HsngBgmV732plCixAMBaw07PAh2ixy0cN83jXqRB
IgGxxNAVdwxsH7nR7sHIxZ8UTppmyA==
=wIi7
-----END PGP SIGNATURE-----