Adding Documentation
11 minute read
To contribute new content pages or improve existing content pages, open a pull request (PR). Make sure you follow all the guidelines in the Getting started section.
If your change is small, or you’re unfamiliar with git, read Changes using GitHub to learn how to edit a page.
If your changes are large, read Work from a local fork to learn how to make changes locally on your computer.
Contributing basics
- Write United Manufacturing Hub documentation in Markdown and build the UMH docs site using Hugo.
- The source is in GitHub.
- Page content types describe the presentation of documentation content in Hugo.
- You can use Docsy shortcodes or custom Hugo shortcodes to contribute to UMH documentation.
- In addition to the standard Hugo shortcodes, we use a number of custom Hugo shortcodes in our documentation to control the presentation of content.
- Documentation source is available in multiple languages in
/content/
. Each language has its own folder with a two-letter code determined by the ISO 639-1 standard . For example, English documentation source is stored in/content/en/docs/
. - For more information about contributing to documentation in multiple languages or starting a new translation, see localization.
Changes using GitHub
If you’re less experienced with git workflows, here’s an easier method of opening a pull request. Figure 1 outlines the steps and the details follow.
Figure 1. Steps for opening a PR using GitHub.
On the page where you see the issue, select the Edit this page option in the right-hand side navigation panel.
Make your changes in the GitHub markdown editor.
Below the editor, fill in the Propose file change form. In the first field, give your commit message a title. In the second field, provide a description.
Do not use any GitHub Keywords in your commit message. You can add those to the pull request description later.
Select Propose file change.
Select Create pull request.
The Open a pull request screen appears. Fill in the form:
- The Subject field of the pull request defaults to the commit summary. You can change it if needed.
- The Body contains your extended commit message, if you have one, and some template text. Add the details the template text asks for, then delete the extra template text.
- Leave the Allow edits from maintainers checkbox selected.
PR descriptions are a great way to help reviewers understand your change. For more information, see Opening a PR.
Select Create pull request.
Addressing feedback in GitHub
Before merging a pull request, UMH community members review and approve it. If you have someone specific in mind, leave a comment with their GitHub username in it.
If a reviewer asks you to make changes:
- Go to the Files changed tab.
- Select the pencil (edit) icon on any files changed by the pull request.
- Make the changes requested.
- Commit the changes.
When your review is complete, a reviewer merges your PR and your changes go live a few minutes later.
Work from a local fork
If you’re more experienced with git, or if your changes are larger than a few lines, work from a local fork.
Make sure you have git installed on your computer. You can also use a git UI application.
Figure 2 shows the steps to follow when you work from a local fork. The details for each step follow.
Figure 2. Working from a local fork to make your changes.
Fork the united-manufacturing-hub/umh.docs.umh.app repository
- Navigate to the united-manufacturing-hub/umh.docs.umh.app repository.
- Select Fork.
Create a local clone and set the upstream
In a terminal window, clone your fork and update the Docsy Hugo theme:
git clone git@github.com/<github_username>/umh.docs.umh.app cd umh.docs.umh.app git submodule update --init --recursive --depth 1
Navigate to the new
umh.docs.umh.app
directory. Set theunited-manufacturing-hub/umh.docs.umh.app
repository as theupstream
remote:cd umh.docs.umh.app git remote add upstream https://github.com/united-manufacturing-hub/umh.docs.umh.app.git
Confirm your
origin
andupstream
repositories:git remote -v
Output is similar to:
origin git@github.com:<github_username>/umh.docs.umh.app.git (fetch) origin git@github.com:<github_username>/umh.docs.umh.app.git (push) upstream https://github.com/united-manufacturing-hub/umh.docs.umh.app.git (fetch) upstream https://github.com/united-manufacturing-hub/umh.docs.umh.app.git (push)
Fetch commits from your fork’s
origin/main
andunited-manufacturing-hub/umh.docs.umh.app
’supstream/main
:git fetch origin git fetch upstream
This makes sure your local repository is up to date before you start making changes.
Create a branch
Decide which branch base to your work on:
- For improvements to existing content, use
upstream/main
. - For new content about existing features, use
upstream/main
. - For localized content, use the localization’s conventions. For more information, see localizing United Manufacturing Hub documentation.
If you need help choosing a branch, reach out on the Discord channel.
- For improvements to existing content, use
Create a new branch based on the branch identified in step 1. This example assumes the base branch is
upstream/main
:git checkout -b <my_new_branch> upstream/main
Make your changes using a text editor.
At any time, use the git status
command to see what files you’ve changed.
Commit your changes
When you are ready to submit a pull request, commit your changes.
In your local repository, check which files you need to commit:
git status
Output is similar to:
On branch <my_new_branch> Your branch is up to date with 'origin/<my_new_branch>'. Changes not staged for commit: (use "git add <file>..." to update what will be committed) (use "git checkout -- <file>..." to discard changes in working directory) modified: content/en/docs/development/contribute/new-content/add-documentation.md no changes added to commit (use "git add" and/or "git commit -a")
Add the files listed under Changes not staged for commit to the commit:
git add <your_file_name>
Repeat this for each file.
After adding all the files, create a commit:
git commit -m "Your commit message"
Do not use any GitHub Keywords in your commit message. You can add those to the pull request description later.
Push your local branch and its new commit to your remote fork:
git push origin <my_new_branch>
Preview your changes locally
It’s a good idea to preview your changes locally before pushing them or opening a pull request. A preview lets you catch build errors or markdown formatting problems.
Install and use the hugo
command on your computer:
Install Hugo.
If you have not updated your website repository, the
website/themes/docsy
directory is empty. The site cannot build without a local copy of the theme. To update the website theme, run:git submodule update --init --recursive --depth 1
In a terminal, go to your United Manufacturing Hub website repository and start the Hugo server:
cd <path_to_your_repo>/umh.docs.umh.app hugo server --buildFuture
In a web browser, navigate to
https://localhost:1313
. Hugo watches the changes and rebuilds the site as needed.To stop the local Hugo instance, go back to the terminal and type
Ctrl+C
, or close the terminal window.
Open a pull request from your fork to united-manufacturing-hub/umh.docs.umh.app
Figure 3 shows the steps to open a PR from your fork to the umh/umh.docs.umh.app. The details follow.
Figure 3. Steps to open a PR from your fork to the umh/umh.docs.umh.app.
In a web browser, go to the united-manufacturing-hub/umh.docs.umh.app repository.
Select New Pull Request.
Select compare across forks.
From the head repository drop-down menu, select your fork.
From the compare drop-down menu, select your branch.
Select Create Pull Request.
Add a description for your pull request:
Title (50 characters or less): Summarize the intent of the change.
Description: Describe the change in more detail.
- If there is a related GitHub issue, include
Fixes #12345
orCloses #12345
in the description. GitHub’s automation closes the mentioned issue after merging the PR if used. If there are other related PRs, link those as well. - If you want advice on something specific, include any questions you’d like reviewers to think about in your description.
- If there is a related GitHub issue, include
Select the Create pull request button.
Congratulations! Your pull request is available in Pull requests.
After opening a PR, GitHub runs automated tests and tries to deploy a preview using Cloudflare Pages.
- If the Cloudflare Page build fails, select Details for more information.
- If the Cloudflare Page build succeeds, select Details opens a staged version of the United Manufacturing Hub website with your changes applied. This is how reviewers check your changes.
You should also add labels to your PR.
Addressing feedback locally
After making your changes, amend your previous commit:
git commit -a --amend
-a
: commits all changes--amend
: amends the previous commit, rather than creating a new one
Update your commit message if needed.
Use
git push origin <my_new_branch>
to push your changes and re-run the Cloudflare tests.If you use
git commit -m
instead of amending, you must squash your commits before merging.
Changes from reviewers
Sometimes reviewers commit to your pull request. Before making any other changes, fetch those commits.
Fetch commits from your remote fork and rebase your working branch:
git fetch origin git rebase origin/<your-branch-name>
After rebasing, force-push new changes to your fork:
git push --force-with-lease origin <your-branch-name>
Merge conflicts and rebasing
For more information, see Git Branching - Basic Branching and Merging, Advanced Merging, or ask in the Discord channel for help.
If another contributor commits changes to the same file in another PR, it can create a merge conflict. You must resolve all merge conflicts in your PR.
Update your fork and rebase your local branch:
git fetch origin git rebase origin/<your-branch-name>
Then force-push the changes to your fork:
git push --force-with-lease origin <your-branch-name>
Fetch changes from
united-manufacturing-hub/umh.docs.umh.app
’supstream/main
and rebase your branch:git fetch upstream git rebase upstream/main
Inspect the results of the rebase:
git status
This results in a number of files marked as conflicted.
Open each conflicted file and look for the conflict markers:
>>>
,<<<
, and===
. Resolve the conflict and delete the conflict marker.For more information, see How conflicts are presented.
Add the files to the changeset:
git add <filename>
Continue the rebase:
git rebase --continue
Repeat steps 2 to 5 as needed.
After applying all commits, the
git status
command shows that the rebase is complete.Force-push the branch to your fork:
git push --force-with-lease origin <your-branch-name>
The pull request no longer shows any conflicts.
Squashing commits
For more information, see Git Tools - Rewriting History, or ask in the Discord channel for help.
If your PR has multiple commits, you must squash them into a single commit before merging your PR.
You can check the number of commits on your PR’s Commits tab or by running the git log
command locally.
This topic assumes vim
as the command line text editor.
Start an interactive rebase:
git rebase -i HEAD~<number_of_commits_in_branch>
Squashing commits is a form of rebasing. The
-i
switch tells git you want to rebase interactively.HEAD~<number_of_commits_in_branch
indicates how many commits to look at for the rebase.Output is similar to:
pick d875112ca Original commit pick 4fa167b80 Address feedback 1 pick 7d54e15ee Address feedback 2 # Rebase 3d18sf680..7d54e15ee onto 3d183f680 (3 commands) ... # These lines can be re-ordered; they are executed from top to bottom.
The first section of the output lists the commits in the rebase. The second section lists the options for each commit. Changing the word
pick
changes the status of the commit once the rebase is complete.For the purposes of rebasing, focus on
squash
andpick
.For more information, see Interactive Mode.
Start editing the file.
Change the original text:
pick d875112ca Original commit pick 4fa167b80 Address feedback 1 pick 7d54e15ee Address feedback 2
To:
pick d875112ca Original commit squash 4fa167b80 Address feedback 1 squash 7d54e15ee Address feedback 2
This squashes commits
4fa167b80 Address feedback 1
and7d54e15ee Address feedback 2
intod875112ca Original commit
, leaving onlyd875112ca Original commit
as a part of the timeline.Save and exit your file.
Push your squashed commit:
git push --force-with-lease origin <branch_name>