Description
Origin of idea
Currently, GitHub does not support pull requests for a repository's wiki. This has been a long-standing issue with GitHub's wiki feature, and there doesn't seem to be any indications that it will change any time soon. The wiki counts as a separate repo from the main repo, but the wiki repo does not support PRs. Our current implementation is that the wiki repo is a submodule within the main repo. This gives us the advantage where local copies of the wiki can be up-to-date with the true wiki. However, it makes contributing, more difficult than it needs to be. Currently, those without write access to the wiki need to make a fork, make their changes, and then make an issue asking for a maintainer to take a look. The maintainer then, if they wish to merge the changes, has to look at the fork and do a merge manually. No PR also means that the change does not get put into the automated release notes, and the author doesn't get appropriate credit.
Additionally, the submodule commit hash in the main repo has to be updated whenever the wiki is updated. This is done automatically by Dependabot, but is still rather annoying.
Suggestion/proposed solution?
Migrate documentation to GitHub pages with a theme such as Just the Docs and with HTTPS enforcement on.
All documentation files would live within the docs folder of the repository.
This would allow for all documentation changes to be submitted via pull requests.
Additionally, pages provide for better flexibility and features extensions than just the GitHub wiki.
For instance, custom themes, custom HTML/CSS, custom build tools outside of Jekyll if necessary (shouldn't be needed), better search that isn't limited to page names, improved organization. Additionally, we can run Jekyll locally to get previews. The markdown of the wiki can also be rendered locally with some tools, but the GitHub-specific flare like the sidebar and style formatting is not visible until actually publishing it.
A potential theme is the very popular just the docs Jekyll theme. https://github.com/just-the-docs/just-the-docs
Migrating the existing content shouldn't be too hard as Jekyll and JTD support markdown, which is what is currently being used.
The main downside is that advertising of the wiki would be tricker. It would no longer be in the Wiki tab of the main repository. We can link to the page via the Read Me, and optionally via the old wiki as well. Additionally, deployment of the page will be slower than the wiki due to the build requirement. (JTD says potentially up to 10 mins)
Required tasks
- Migrate old documentation to the new format
- Enable GitHub pages and set it to deploy from /docs of the main branch.
- Remove the wiki submodule from the wiki
- Add page link to the read me and the repo about section
- Change the wiki link under help for RimSort to point to the page
- Change the wiki link in the issues template
- Disable/Deprecate the old Wiki (Note that disabling the wiki will make wiki links redirect to the main repo page. Older RimSort versions with old links will do this if redirected. This may cause some confusion, but IMO this is cleaner and easier to deal with. There is a massively reduced risk of a user using old documentation. As long as the page is sufficiently advertised, it shouldn't be an issue to simply disable it.)
Alternatives considered
Using GitHub actions/workflow for wiki contents syncing.
Get rid of the submodule in the wiki. Instead, keep a copy of the wiki within the repository. Consider the actual wiki repo to be read only by users (restrict edit to users with push access is already a thing, but for those with push access, they will likely need to just self-impose this restriction, or we add a more stringent script to deal with it easier).
On merge with the default branch, where the documentation files have been modified, run a workflow that does the following:
- Setup git with the user and email being the GitHub bot (The checkout action should do this by default already README: Suggest
user.emailto be41898282+github-actions[bot]@users.noreply.github.comactions/checkout#1707)- Clone the wiki repo (Depth 1 should be enough)
- Copy all documentation files from the main repo into the local wiki repo
- CD to the wiki repo
- Check for changes in the working directory and for untracked files
5.5 If there are no changes or untracked files, exit with exit code 0 (Nothing to do)- If there are changes or untracked files, add all untracked files and make a new commit
- Add the origin-wiki as a remote, with the action GITHUB_TOKEN (with write access) assigned to the user
- Push to origin-wiki
- Go in reverse and copy from the wiki into the main repo and merge (May need to make a new branch and PR for this due to branch protection rules.)
Additionally, any commit messages should include the full sem ver from the semver action.
The issue with this solution is mainly added complexity in workflows, potential issues with syncing, and the potential to go badly if something goes wrong. Essentially, if it works well, it could be a viable solution, but if it breaks or works badly, it can cause excessive issues, especially if reverse syncing is implemented. Additionally, pages has the upside of more control.
Additional context
About GitHub wiki PRs: https://stackoverflow.com/questions/10642928/how-can-i-make-a-pull-request-for-a-wiki-page-on-github
About GitHub Pages: https://docs.github.com/en/pages/quickstart
Just the Docs template: https://github.com/just-the-docs/just-the-docs-template
Migrating to JTD fin an existing project: https://github.com/just-the-docs/just-the-docs-template?tab=readme-ov-file#hosting-your-docs-from-an-existing-project-repo
Code of Conduct
- I agree to follow this project's Code of Conduct
Duplicate Issue Check
- I've checked for duplicate issues
Wiki/FAQ Check
- I've checked the Wiki for a solution