This was created to provide an easy way for anybody to use GitLab to create a handbook to meet the new remote working style.
GitLab's handbook is part of a larger website and blog project so any attempt to use it as a starting point would be problematic.
This project exists to compensate for that with as little command-line activity as possible. Forks were disabled because they create a relationship between projects. To use this one, please export and import it into your own account.
There are some configurations that need to happen for this to be used for your own purposes.
- Use the Web IDE to modify the
config.tomlwith a fitting title - Remove any template content that doesn't belong in your handbook
- Update the README to contain instructions for contributing pages
- Use GitLab Pages with the gitlab.io URL until your company DNS
If you want to checkout the repo to make local copies and run the local review app, be sure to do:
git clone [email protected]:brownfield-dev/remote/handbook.git
cd handbook
git submodule update --init --recursiveThe theme is currently in a submodule which needs to be pulled.
If there's an error about "Shortcode 'columns' not found", that means the submodule didn't get fetched. Use git submodule update to retrieve that content.
GitLab offers a lot of workflow flexibility depending on the size of your team and type of content in the handbook.
If your handbook is meant to have company confidential information in it, be sure to set the project to private and the "GitLab Pages" accessibility to "Only Project Members" to prevent disclosure.
Since project configurations and master branch changes are controlled by Maintainer roles, be sure to restrict that permission level to individuals authorized to speak for the organization. If these are non-technical personnel, they can use the Merge Request feature to review content without the requirement to do any git commands or fancy technical activity.
The suggested workflow comes from GitLab Flow and follows these steps:
- Individual identifies content that needs to be added or changed
- Individual creates an issue in the project with the change they intend to make (use "content update" template)
- Individual clicks the
Create Merge Requestbutton from the issue - Individual opens the Merge Request, clicks on
Web IDEor checkout code if familiar with git - Individual creates new pages or updates existing pages
- Individual
Resolves WIP Statusin Merge Request and assigns to a maintainer - Maintainer reviews change in Merge Request screen using the
Changestab - Maintainer provides feedback on the specific code (comment on a line or section)
- Individual updates the page as directed or discusses further
- Maintainer merges the change
The important part of this flow is that the changes need to be small. Creating many merge request that only incrementally improve the handbook is acceptable. If the net benefit is at all positive, it should be merged and then follow-up issues or MRs created to address any additional content updates.
The other thing you may notice is that there's no meeting or discussion or concensus building that takes place in the workflow. The individual should be empowered to fix any pages they believe require improvement. Silver license tier has approvals depending on the change.
Don't be afraid to flag content as deprecated or invalid or until an update can be created. Deleting content entirely is also good if it's incorrect, but leaving the pages in will serve as a reminder to execute the update.
In this repositiry is an example issue template for "Change content" which is based on the GitLab issue for requesting a change. This makes a lot of assumptions and parts are likely not applicable. It may make sense to duplicate it for various sections.
These templates are in .gitlab/issue_templates/ and the filename is used in the dropdown list for creating a new issue.
Adding quick actions to the bottom of the issue can do things like label them or notify a group.