-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA256 On Sun, Dec 08, 2024 at 09:06:00PM +0100, Marek Marczykowski-Górecki wrote: > 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 :)
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----- -- You received this message because you are subscribed to the Google Groups "qubes-devel" group. To unsubscribe from this group and stop receiving emails from it, send an email to qubes-devel+unsubscr...@googlegroups.com. To view this discussion visit https://groups.google.com/d/msgid/qubes-devel/Z1-UFyjQFYfO5Re5%40mail-itl.
