Adding Documentation

To contribute new content pages or improve existing content pages, open a pull request (PR). Make sure you follow all the general contributing guidelines in the Getting started section, as well as the documentation specific guidelines.

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.

1. On the page where you see the issue, select the Edit this page option in the right-hand side navigation panel.

2. Make your changes in the GitHub markdown editor.

3. 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.

4. Select Propose file change.

5. Select Create pull request.

6. 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.

7. 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:

1. Go to the Files changed tab.
2. Select the pencil (edit) icon on any files changed by the pull request.
3. Make the changes requested.
4. 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 setup your local environment before you start.

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

1. Navigate to the united-manufacturing-hub/umh.docs.umh.app repository.
2. Select Fork.

Fetch commits

Before proceeding, verify that your environment is setup correctly.

1. Confirm your origin and upstream repositories:

   git remote -v
   

   Output is similar to:

   origin  https://github.com/<github_username>/umh.docs.umh.app.git (fetch)
   origin  https://github.com/<github_username>/umh.docs.umh.app.git (push)
   upstream        https://github.com/united-manufacturing-hub/umh.docs.umh.app.git (fetch)
   upstream        no_push (push)
   

2. Fetch commits from your fork’s origin/main and united-manufacturing-hub/umh.docs.umh.app’s upstream/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

1. 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.
   • It is helpful to name branches like [Purpose]/[ID]/[Title] where Purpose is docs, feat, or fix and ID is the issue identifier (or xxx if there is no related issue).

   If you need help choosing a branch, reach out on the Discord channel.

2. 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
   

3. 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.

1. 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")
   

2. Add the files listed under Changes not staged for commit to the commit:

   git add <your_file_name>
   

   Repeat this for each file.

3. 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.

4. 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:

1. Install Hugo.

2. 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
   

3. 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
   

   Alternatively, if you have installed GNU make and GNU awk:

   cd <path_to_your_repo>
   make serve
   

4. In a web browser, navigate to https://localhost:1313. Hugo watches the changes and rebuilds the site as needed.

5. 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.

1. In a web browser, go to the united-manufacturing-hub/umh.docs.umh.app repository.

2. Select New Pull Request.

3. Select compare across forks.

4. From the head repository drop-down menu, select your fork.

5. From the compare drop-down menu, select your branch.

6. Select Create Pull Request.

7. 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 or Closes #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.

8. 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

1. 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

2. Update your commit message if needed.

3. 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.

1. Fetch commits from your remote fork and rebase your working branch:

   git fetch origin
   git rebase origin/<your-branch-name>
   

2. 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.

1. 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>
   

2. Fetch changes from united-manufacturing-hub/umh.docs.umh.app’s upstream/main and rebase your branch:

   git fetch upstream
   git rebase upstream/main
   

3. Inspect the results of the rebase:

   git status
   

   This results in a number of files marked as conflicted.

4. 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.

5. Add the files to the changeset:

   git add <filename>
   

6. Continue the rebase:

   git rebase --continue
   

7. Repeat steps 2 to 5 as needed.

   After applying all commits, the git status command shows that the rebase is complete.

8. 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.

1. 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 and pick.

   For more information, see Interactive Mode.

2. 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 and 7d54e15ee Address feedback 2 into d875112ca Original commit, leaving only d875112ca Original commit as a part of the timeline.

3. Save and exit your file.

4. Push your squashed commit:

   git push --force-with-lease origin <branch_name>