canonical / canonical/sphinx-stack
Friction staying in sync with starter pack
- Dominant language
- No language data
- Stars
- 37
- Forks
- 77
- Avg merge
- 1d 5h
- Merged PRs (30d)
- 3
Description
I've been using the starter pack for almost six months now (great work, btw!) and in that time, there have been some substantial changes between the when I started and where the pack is at now.
I've done two major updates to my team's documentation in that time, specifically these:
https://github.com/canonical/iot-field-docs/pull/33
https://github.com/canonical/iot-field-docs/pull/46
You can see in that first PR a comment:
> NB last commit:
>
> Rebasing on the starter pack is hard in general as there are many files
in the starter pack which do not matter for us. It would be preferable
if the starter pack structure we adopt were kept separate from the
starter pack's own documentation. This is how they decided to do it, so
we adapt.
Changes are cherry-picks from relevant commits added to the starter pack
since this repository was created, namely ~1.1.0. Any irrelevant changes
in the picked commit are dropped.
>
> This will require tedious intervention. We should try to stay on top of it.
In an ideal world, staying in sync with important changes made in the starter pack (such as switching to vale or fixing Makefile bugs) would be as simple as `git fetch ...; git rebase ...`. However, this is not possible - there are files which overlap between the two repositories, many of which I either do not wish to be modified (the various `index` files, `CHANGELOG`) or which would cause chaos if added (a bunch of starter pack documentation pages to my own repository).
My current practice then is to examine each commit since my last sync and identify if there are relevant changes. Sometimes, there aren't any (they're changes purely to the documentation of the starter pack, which I am uninterested in), and sometimes there are some which conflict (modifications to the `CHANGELOG` but also fixes to the `Makefile`).
Currently, this is not very challenging or time consuming to achieve (it helps that I stay on top of it, of course). But it *is* tedious. I appreciate the work y'all do to update things - I definitely don't want to maintain testing or `requirements.txt` files - and am glad it is done for me! I'd like to keep that.
I would recommend that the core elements of the starter pack that other teams would be interested in:
* `.sphinx`
* `.custom_wordlist.txt`
* `.gitignore`
* `Makefile`
* `conf.py`
* `requirements.txt`
stick around -- resolving conflicts in `conf.py` are relatively straight-forward and should be obvious to anybody familiar with doing so, and the rest (I think) are correctly maintained by TAs.
I think that the rest of the content should be somewhere else separate from the starter pack. While it is nice to have the starter pack's documentation alongside the code which makes it, it does not feel worth the labor trade-off for folx who want to stay up to date.
Something like a git submodule for the other components seems like a natural choice, but that of course presents its own issues; it would make the *most* sense that `docs/` be made the submodule, but of course then all the files I care about are stuck in a submodule and I don't get to maintain them!
Resolving this issue either requires conceding that this will feel bad for teams maintaining documentation (and effectively discourage staying up to date) or restructuring much of the repository in a way that will cause some immense pain for anyone already using the starter pack (similar to the pre- and post-extension troubles).
Sorry I don't have a solution, this is just the major point of friction I have with the way things work currently :)
Contributor guide
Assessment
This issue has not been assessed yet.