Editing docs (#6)

book.toml

@@ -12,4 +12,6 @@ build-dir = "out"
 create-missing = false
 
 [output.html]
+git-repository-url = "https://github.com/DanNixon/maker-space-wiki"
+edit-url-template = "https://github.com/DanNixon/maker-space-wiki/edit/main/{path}"
 fold.enable = true

src/SUMMARY.md

@@ -8,6 +8,7 @@
     - [Proposed Solution](./proposal/proposed_solution/README.md)
         - [Technical Details](./proposal/proposed_solution/technical_details.md)
         - [Editing Workflow](./proposal/proposed_solution/editing_workflow.md)
+        - [Implementation Plan](./proposal/proposed_solution/implementation_plan.md)
     - [Hypothetically Asked Questions](./proposal/hypothetically_asked_questions.md)
 - [Equipment](./equipment/README.md)
     - [Laser Cutter](./equipment/laser_cutter/README.md)

src/introduction.md

@@ -3,3 +3,9 @@
 Welcome to the [Maker Space](https://www.makerspace.org.uk/) wiki!
 
 Here you will find (hopefully) all the information you could possibly want to know about our hackspace, how it works, what facilities we have and how to use them.
+
+## But really, what is this?
+
+This is a demo wiki, if you are looking for the current wiki then head [here](https://makerspace.pbworks.com/).
+
+This contains the actual proposal to change from our existing wiki to something very like this as well as a couple of demo pages that were either quick to write, quick to migrate or generously donated as part of testing.

src/proposal/proposed_solution/README.md

@@ -29,3 +29,5 @@ It depends, do you...
 
 - [care about how this actually works?](./technical_details.md), or
 - [just want to know how you would edit the wiki?](./editing_workflow.md)
+
+You may also be interested in the [implementation plan](./implementation_plan.md).

src/proposal/proposed_solution/editing_workflow.md

@@ -1,3 +1,38 @@
 # Editing Workflow
 
-TODO
+Please note, this document is just an overview of the processes available, it is **not** documentation of how to author the wiki.
+Actual documentation will be written in due course should this solution be selected.
+
+In general, there are two options: editing entirely via the GitHub website, or editing locally with Git setup.
+If you are comfortable with Git then you likely want to use the latter option, if you are new to Git or only need to make a small change then the former option is best.
+
+## Making changes
+
+### Editing an existing page
+
+If you just want to edit a single page then you may follow the edit link in the top right hand corner of the page.
+Assuming you are signed in to GitHub, this will take you directly to a page where you can edit the contents and submit a Pull Request.
+
+### Editing the wiki using GitHub via the web browser
+
+Files may be uploaded via the GitHub website (text or images) and edited via GitHub's text editor.
+After uploading or editing files GitHub will prompt you to commit them and optionally create a Pull Request.
+
+### Editing the wiki locally
+
+I am lazily going to assume I don't need to say much here.
+If you are familiar with Git then follow the usual create branch, do changes, commit, push, open Pull Request workflow.
+
+It is possible to run mdBook locally, or just use any Markdown renderer you may already have to preview changes.
+
+## After the Pull Request has been created
+
+One may wish to ask for people to review it, e.g. if you have editing a page relating to the CNC mill then you may wish to ask David Pye to look over it.
+
+Whenever a new commit is added to a Pull Request, a GitHub Action runs which builds the page and deploys it in a test environment, allowing to to see exactly what your changes will actually look like.
+A bot will comment on the Pull Request with a link you can follow to read the wiki with your changes applied (always use the most recent comment).
+
+If the bot did not post a comment, then check the status of the Action, it may show a red cross indicating that something has gone wrong.
+You will have to inspect the logs to see exactly what the issue is, if it is an error from mdBook then they are usually pretty descriptive as to what is wrong.
+
+When happy the PR is merged, an Action runs and the live wiki is updated.

src/proposal/proposed_solution/implementation_plan.md

@@ -0,0 +1,14 @@
+# Implementation Plan
+
+A general idea of how this will be put into practice.
+
+1. Create a Cloudflare Pages project named "makerspace-wiki" (or something close to that) under the Maker Space account
+1. Create a repository named "wiki" under the MakerSpaceNewcastle GitHub organisation containing all but the content of the repository behind this wiki
+1. Create an API key allowing publishing to the above project and store it as a repository Actions secret in the above repository
+1. See that GitHub Actions publishes to the Cloudflare Pages project
+1. Apply repository settings described in [technical details](./technical_details.md)
+1. Apply DNS settings described in [technical details](./technical_details.md)
+1. Move the repository behind this demo wiki under the MakerSpaceNewcastle organisation and archive it
+1. Begin migrating content to/creating content on the new wiki
+1. Once the new wiki contains all of the useful information from the old wiki, replace any wiki links with `wiki.makerspace.org.uk`
+1. When we are certain that any useful content has been migrated from the old wiki, delete it.

src/proposal/proposed_solution/technical_details.md

@@ -45,6 +45,50 @@ If there is a need for a quick revert to an older version, then this can be done
 
 ## History
 
-Deployments to Cloudflare Pages are reported in GitHub as deployments, and the previous versions of the site are available to browse if desired (see for this wiki [here](https://github.com/DanNixon/maker-space-wiki/deployments)).
+A link to the specific Cloudflare Pages deployment can be found in the GitHub Actions logs for the specific commit, selected via the green tick next to a commit on the GitHub website.
+e.g. click the green tick on [commit](https://github.com/DanNixon/maker-space-wiki/commit/270333e4d4b3c0fb611336801446630151f08546), then details to get to [actions logs](https://github.com/DanNixon/maker-space-wiki/actions/runs/10653671421/job/29529029806) and the link is shown in the logs for the "Publish to Cloudflare Pages" step under "Running Wrangler Commands".
+In future this may be easier when the appropriate GitHub Action for Cloudflare Wrangler interact with GitHub Deployments.
 
 The history of the source files can be viewed, managed and manipulated via all the standard Git methods if the need to do so should arise.
+
+## Specific settings/configurations
+
+Here are some specific and/or low level settings that will be used.
+
+### GitHub
+
+#### General Pull Request settings
+
+- "Allow merge commits" - uncheck
+- "Allow squash merging" - check
+    - "Default commit message" - "Pull request title and description"
+- "Allow rebase merging" - uncheck
+- "Automatically delete head branches" - check
+
+#### Branch ruleset for `main`:
+
+- "Restrict deletions"
+- "Require linear history"
+- "Require a pull request before merging"
+    - "Dismiss stale pull request approvals when new commits are pushed"
+- "Require status checks to pass"
+- "Block force pushes"
+
+This forces all changes to be made via a Pull Request, ensuring that commits that may break the site build cannot be pushed directly to `main`.
+If we ever did want to require approval in the future, this is the place one would configure it.
+
+#### Actions permissions
+
+- "Fork pull request workflows from outside collaborators" - "Require approval for all outside collaborators"
+
+This ensures that actions will not run (unless manually allowed) on any Pull Request from a GitHub user who is not part of the MakerSpaceNewcastle.
+This is done to protect the Cloudflare API token.
+
+It is the intention that members with a GitHub account are members of the MakerSpaceNewcastle GitHub organisation, so this should not be a common issue.
+
+### Cloudflare
+
+DNS: `CNAME wiki makerspace-wiki.pages.dev`.
+
+Assuming the Pages project is called `makerspace-wiki`, this will result in the wiki being availale at `wiki.makerspace.org.uk`.
+This is actually handled automatically by Cloudflare following the custom domain config in Pages, it is just here for the sake of completeness.