-
Notifications
You must be signed in to change notification settings - Fork 0
README
Repository template to manage a GitHub wiki that is synchronized with a GitHub project.
This wiki is synchronized with the project-repo-template.
The structure is loosely related to the arc42 documentation.
To create system views, you should take a look at C4, and the related Structurizr DSL.
This template is tailored to GitHub repositories, but the core concepts work for any project using a version control system.
Steps to adapt this template.
- Add the wiki repository of your project repository as additional remote (checkout the sync-wiki action for more information)
- Change the link in sync-wiki action to point to your remote project wiki
- Adapt the Definition of Done in the pull request template
- Optional: Adapt the license to be in sync with the license of your project
- Adapt the existing markdown pages (see template placeholders for more details)
GitHub wiki only considers files, and ignores any hierarchy set via folders. This enforces that every filename must be unique in the entire wiki.
This template is structured in a way to group related files, and enforce an order to first show more important pages on the wiki.
In this template, many sections include placeholder text to provide some guidance of what the section should be about.
These placeholders are inside {{ }} blocks.
Some sections also include example content that is given inside [[ ]] blocks.
Every GitHub wiki has its own git repository, with the link to it shown on the sidebar of the wiki.
This setup allows edits directly in the wiki section of a project, but makes it hard to encourage external contributions, because the common PR workflow is not available.
Therefore, this template should be placed in its own repository, and synchronize changes to the internal repository of the project wiki.
Since the wiki is shown in the project repository, issues should still be handled in the project repository, because users would expect this.
To enforce this, the issue tab is deactivated in this template. More precisely, every feature except PRs was disabled, to make it clear that everything except PRs should be handled in the project repository.
This template contains the following GitHub actions:
-
sync_wiki... Automatically pushes changes to the wiki repository of the associated project
Repositories created by GitHub templates do not adopt the issue/PR labels set in the template. Instead, each one must be copied manually, which is unfortunate, but must only be done once.
Below are the labels defined in the wiki template:
-
blocked... Marks this PR that it is blocked by another issue/PR (Color:#F83A55) -
declined... This PR was declined (Color:#ffffff) -
waiting-on-assignee... PR author or reviewer is awaiting response from assignee (Color:#FEF2C0) -
waiting-on-author... Assignee or reviewer is awaiting response from PR author (Color:#463F12) -
waiting-on-reviewer... Author or assignee is awaiting response from reviewer (Color:#E6A2AE)
Repository settings are not adopted from templates, and must be set manually. Below are the recommended settings that work well with this wiki template.
General Settings:
- Disable all features to only allow pull requests
- Only allow squash merging for pull requests
- Automatically delete head branches
MIT Licensed
{{
Footer that is displayed on every wiki page
}}
[[
Please create an issue if you found any spelling mistakes.
You may also create an issue if you think the content of this wiki should be improved.
Note: This wiki is managed in its own repository. Any commits made using the edit button will be overwritten.
Note: Issues for the wiki are handled in the project-repo-template, but pull requests for the wiki are handled in the project-wiki-template.
This wiki is MIT licensed, and works together with the project-repo-template. Serving as template repositories for new GitHub projects.
]]