Contributing new content

• 1: GitHub Workflow
• 2: Pull Request Process
• 3: Adding Documentation
• 4: Suggesting content improvements

1 - GitHub Workflow

1. Fork in the cloud

1. Go to the repository page.
2. Click Fork button (top right) to establish a cloud-based fork.

2. Clone fork to local storage

Per Go’s workspace instructions, place United Manufacturing Hub’s code on your GOPATH using the following cloning procedure.

In your shell, define a local working directory as working_dir. If your GOPATH has multiple paths, pick just one and use it instead of $GOPATH. You must follow exactly this pattern, neither $GOPATH/src/github.com/${your github profile name}/ nor any other pattern will work.

The following instructions assume you are using a bash shell. If you are using a different shell, you will need to adjust the commands accordingly.

export working_dir="$(go env GOPATH)/src/github.com/"

Set user to match your github profile name:

export user=<your github profile name>

Both $working_dir and $user are mentioned in the figure above.

Create your clone:

mkdir -p $working_dir
cd $working_dir
git clone https://github.com/$user/united-manufacturing-hub.git
# or: git clone [email protected]:$user/united-manufacturing-hub.git

cd $working_dir/united-manufacturing-hub
git remote add origin https://github.com/united-manufacturing-hub/united-manufacturing-hub.git
# or: git remote add upstream [email protected]:united-manufacturing-hub/united-manufacturing-hub.git

# Never push to upstream master
git remote set-url --push origin no_push

# Confirm that your remotes make sense:
git remote -v

3. Create a Working Branch

Get your local master up to date.

cd $working_dir/united-manufacturing-hub
git fetch origin
git checkout main
git rebase origin/main

Create your new branch.

git checkout -b myfeature

You may now edit files on the myfeature branch.

4. Keep your branch in sync

You will need to periodically fetch changes from the origin repository to keep your working branch in sync.

Make sure your local repository is on your working branch and run the following commands to keep it in sync:

git fetch origin
git rebase origin/main

Please don’t use git pull instead of the above fetch and rebase. Since git pull executes a merge, it creates merge commits. These make the commit history messy and violate the principle that commits ought to be individually understandable and useful (see below).

You might also consider changing your .git/config file via git config branch.autoSetupRebase always to change the behavior of git pull, or another non-merge option such as git pull --rebase.

5. Commit Your Changes

You will probably want to regularly commit your changes. It is likely that you will go back and edit, build, and test multiple times. After a few cycles of this, you might amend your previous commit.

git commit

6. Push to GitHub

When your changes are ready for review, push your working branch to your fork on GitHub.

git push -f <your_remote_name> myfeature

7. Create a Pull Request

1. Visit your fork at https://github.com/<user>/united-manufacturing-hub
2. Click the Compare & Pull Request button next to your myfeature branch.
3. Check out the pull request process for more details and advice.

Get a code review

Once your pull request has been opened it will be assigned to one or more reviewers. Those reviewers will do a thorough code review, looking for correctness, bugs, opportunities for improvement, documentation and comments, and style.

Commit changes made in response to review comments to the same branch on your fork.

Very small PRs are easy to review. Very large PRs are very difficult to review.

Squash commits

After a review, prepare your PR for merging by squashing your commits.

All commits left on your branch after a review should represent meaningful milestones or units of work. Use commits to add clarity to the development and review process.

Before merging a PR, squash the following kinds of commits:

• Fixes/review feedback
• Typos
• Merges and rebases
• Work in progress

Aim to have every commit in a PR compile and pass tests independently if you can, but it’s not a requirement. In particular, merge commits must be removed, as they will not pass tests.

To squash your commits, perform an interactive rebase:

1. Check your git branch:

   git status
   

   The output should be similar to this:

   On branch your-contribution
   Your branch is up to date with 'origin/your-contribution'.
   

2. Start an interactive rebase using a specific commit hash, or count backwards from your last commit using HEAD~<n>, where <n> represents the number of commits to include in the rebase.

   git rebase -i HEAD~3
   

   The output should be similar to this:

   pick 2ebe926 Original commit
   pick 31f33e9 Address feedback
   pick b0315fe Second unit of work
   
   # Rebase 7c34fc9..b0315ff onto 7c34fc9 (3 commands)
   #
   # Commands:
   # p, pick <commit> = use commit
   # r, reword <commit> = use commit, but edit the commit message
   # e, edit <commit> = use commit, but stop for amending
   # s, squash <commit> = use commit, but meld into previous commit
   # f, fixup <commit> = like "squash", but discard this commit's log message
   
   ...
   

3. Use a command line text editor to change the word pick to squash for the commits you want to squash, then save your changes and continue the rebase:

   pick 2ebe926 Original commit
   squash 31f33e9 Address feedback
   pick b0315fe Second unit of work
   
   ...
   

   The output after saving changes should look similar to this:

   [detached HEAD 61fdded] Second unit of work
    Date: Thu Mar 5 19:01:32 2020 +0100
    2 files changed, 15 insertions(+), 1 deletion(-)
   
    ...
   
   Successfully rebased and updated refs/heads/master.
   

4. Force push your changes to your remote branch:

   git push --force
   

For mass automated fixups such as automated doc formatting, use one or more commits for the changes to tooling and a final commit to apply the fixup en masse. This makes reviews easier.

By squashing locally, you control the commit message(s) for your work, and can separate a large PR into logically separate changes. For example: you have a pull request that is code complete and has 24 commits. You rebase this against the same merge base, simplifying the change to two commits. Each of those two commits represents a single logical change and each commit message summarizes what changes. Reviewers see that the set of changes are now understandable, and approve your PR.

Merging a commit

Once you’ve received review and approval, your commits are squashed, your PR is ready for merging.

Merging happens automatically after both a Reviewer and Approver have approved the PR. If you haven’t squashed your commits, they may ask you to do so before approving a PR.

Reverting a commit

In case you wish to revert a commit, use the following instructions.

If you have upstream write access, please refrain from using the Revert button in the GitHub UI for creating the PR, because GitHub will create the PR branch inside the main repository rather than inside your fork.

• Create a branch and sync it with upstream.

  # create a branch
  git checkout -b myrevert
  
  # sync the branch with upstream
  git fetch origin
  git rebase origin/main
  

• If the commit you wish to revert is a merge commit, use this command:

  # SHA is the hash of the merge commit you wish to revert
  git revert -m 1 <SHA>
  

  If it is a single commit, use this command:

  # SHA is the hash of the single commit you wish to revert
  git revert <SHA>
  

• This will create a new commit reverting the changes. Push this new commit to your remote.

  git push <your_remote_name> myrevert
  

• Finally, create a Pull Request using this branch.

2 - Pull Request Process

This doc explains the process and best practices for submitting a pull request to the United Manufacturing Hub project and its associated sub-repositories. It should serve as a reference for all contributors, and be useful especially to new and infrequent submitters.

Before You Submit a Pull Request

This guide is for contributors who already have a pull request to submit. If you’re looking for information on setting up your developer environment and creating code to contribute to United Manufacturing Hub, or you are a first-time contributor, see the Contributor Guide to get started.

Make sure your pull request adheres to our best practices. These include following project conventions, making small pull requests, and commenting thoroughly. Please read the more detailed section on Best Practices for Faster Reviews at the end of this doc.

The Pull Request Submit Process

Merging a pull request requires the following steps to be completed before the pull request will be merged.

• Sign the CLA (prerequisite)
• Open a pull request
• Pass all e2e tests
• Get all necessary approvals from reviewers and code owners

Marking Unfinished Pull Requests

If you want to solicit reviews before the implementation of your pull request is complete, you should hold your pull request to ensure that a maintainer does not merge it prematurely.

There are three methods to achieve this:

1. You may add the status: in-progress or status: on-hold labels
2. You may add or remove a WIP or [WIP] prefix to your pull request title
3. You may open your pull request in a draft state

While either method is acceptable, we recommend using the status: in-progress label.

How the e2e Tests Work

United Manufacturing Hub runs a set of end-to-end tests (e2e tests) on pull requests. You can find an overview of the tests in the CI documentation.

Why was my pull request closed?

Closed pull requests are easy to recreate, and little work is lost by closing a pull request that subsequently needs to be reopened. We want to limit the total number of pull requests in flight to:

• Maintain a clean project
• Remove old pull requests that would be difficult to rebase as the underlying code has changed over time
• Encourage code velocity

Best Practices for Faster Reviews

Most of this section is not specific to United Manufacturing Hub, but it’s good to keep these best practices in mind when you’re making a pull request.

You’ve just had a brilliant idea on how to make United Manufacturing Hub better. Let’s call that idea Feature-X. Feature-X is not even that complicated. You have a pretty good idea of how to implement it. You jump in and implement it, fixing a bunch of stuff along the way. You send your pull request - this is awesome! And it sits. And sits. A week goes by and nobody reviews it. Finally, someone offers a few comments, which you fix up and wait for more review. And you wait. Another week or two go by. This is horrible.

Let’s talk about best practices so your pull request gets reviewed quickly.

Familiarize yourself with project conventions

• Development guide
• Coding conventions

Is the feature wanted? File a United Manufacturing Hub Enhancement Proposal

Are you sure Feature-X is something the UMH team wants or will accept? Is it implemented to fit with other changes in flight? Are you willing to bet a few days or weeks of work on it?

It’s better to get confirmation beforehand.

Even for small changes, it is often a good idea to gather feedback on an issue you filed, or even simply ask in UMH Discord channel to invite discussion and feedback from code owners.

KISS, YAGNI, MVP, etc

Sometimes we need to remind each other of core tenets of software design - Keep It Simple, You Aren’t Gonna Need It, Minimum Viable Product, and so on. Adding a feature “because we might need it later” is antithetical to software that ships. Add the things you need NOW and (ideally) leave room for things you might need later - but don’t implement them now.

Smaller Is Better: Small Commits, Small Pull Requests

Small commits and small pull requests get reviewed faster and are more likely to be correct than big ones.

Attention is a scarce resource. If your pull request takes 60 minutes to review, the reviewer’s eye for detail is not as keen in the last 30 minutes as it was in the first. It might not get reviewed at all if it requires a large continuous block of time from the reviewer.

Breaking up commits

Break up your pull request into multiple commits, at logical break points.

Making a series of discrete commits is a powerful way to express the evolution of an idea or the different ideas that make up a single feature. Strive to group logically distinct ideas into separate commits.

For example, if you found that Feature-X needed some prefactoring to fit in, make a commit that JUST does that prefactoring. Then make a new commit for Feature-X.

Strike a balance with the number of commits. A pull request with 25 commits is still very cumbersome to review, so use your best judgment.

Breaking up Pull Requests

Or, going back to our prerefactoring example, you could also fork a new branch, do the prefactoring there and send a pull request for that. If you can extract whole ideas from your pull request and send those as pull requests of their own, you can avoid the painful problem of continually rebasing.

Multiple small pull requests are often better than multiple commits. Don’t worry about flooding us with pull requests. We’d rather have 100 small, obvious pull requests than 10 unreviewable monoliths.

We want every pull request to be useful on its own, so use your best judgment on what should be a pull request vs. a commit.

As a rule of thumb, if your pull request is directly related to Feature-X and nothing else, it should probably be part of the Feature-X pull request. If you can explain why you are doing seemingly no-op work (“it makes the Feature-X change easier, I promise”) we’ll probably be OK with it. If you can imagine someone finding value independently of Feature-X, try it as a pull request. (Do not link pull requests by # in a commit description, because GitHub creates lots of spam. Instead, reference other pull requests via the pull request your commit is in.)

Open a Different Pull Request for Fixes and Generic Features

Put changes that are unrelated to your feature into a different pull request

Often, as you are implementing Feature-X, you will find bad comments, poorly named functions, bad structure, weak type-safety, etc.

You absolutely should fix those things (or at least file issues, please) - but not in the same pull request as your feature. Otherwise, your diff will have way too many changes, and your reviewer won’t see the forest for the trees.

Look for opportunities to pull out generic features

For example, if you find yourself touching a lot of modules, think about the dependencies you are introducing between packages. Can some of what you’re doing be made more generic and moved up and out of the Feature-X package? Do you need to use a function or type from an otherwise unrelated package? If so, promote! We have places for hosting more generic code.

Likewise, if Feature-X is similar in form to Feature-W which was checked in last month, and you’re duplicating some tricky stuff from Feature-W, consider prerefactoring the core logic out and using it in both Feature-W and Feature-X. (Do that in its own commit or pull request, please.)

Comments Matter

In your code, if someone might not understand why you did something (or you won’t remember why later), comment it. Many code-review comments are about this exact issue.

If you think there’s something pretty obvious that we could follow up on, add a TODO.

Read up on GoDoc - follow those general rules for comments.

Test

Nothing is more frustrating than starting a review, only to find that the tests are inadequate or absent. Very few pull requests can touch the code and NOT touch tests.

If you don’t know how to test Feature-X, please ask! We’ll be happy to help you design things for easy testing or to suggest appropriate test cases.

Squashing

Your reviewer has finally sent you feedback on Feature-X.

Make the fixups, and don’t squash yet. Put them in a new commit, and re-push. That way your reviewer can look at the new commit on its own, which is much faster than starting over.

We might still ask you to clean up your commits at the very end for the sake of a more readable history, but don’t do this until asked: typically at the point where the pull request would otherwise be tagged LGTM.

Each commit should have a good title line (<70 characters) and include an additional description paragraph describing in more detail the change intended.

For more information, see squash commits.

General squashing guidelines

• Sausage => squash

  Do squash when there are several commits to fix bugs in the original commit(s), address reviewer feedback, etc. Really we only want to see the end state, and commit message for the whole pull request.

• Layers => don’t squash

  Don’t squash when there are independent changes layered to achieve a single goal. For instance, writing a code munger could be one commit, applying it could be another, and adding a precommit check could be a third. One could argue they should be separate pull requests, but there’s really no way to test/review the munger without seeing it applied, and there needs to be a precommit check to ensure the munged output doesn’t immediately get out of date.

Commit Message Guidelines

PR comments are not represented in the commit history. Commits and their commit messages are the “permanent record” of the changes being done in your PR and their commit messages should accurately describe both what and why it is being done.

Commit messages are comprised of two parts; the subject and the body.

The subject is the first line of the commit message and is often the only part that is needed for small or trivial changes. Those may be done as “one liners” with the git commit -m or the --message flag, but only if the what and especially why can be fully described in that few words.

The commit message body is the portion of text below the subject when you run git commit without the -m flag which will open the commit message for editing in your preferred editor. Typing a few further sentences of clarification is a useful investment in time both for your reviews and overall later project maintenance.

This is the commit message subject

Any text here is the commit message body
Some text
Some more text
...

# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# On branch example
# Changes to be committed:
#   ...
#

Use these guidelines below to help craft a well formatted commit message. These can be largely attributed to the previous work of Chris Beams, Tim Pope, Scott Chacon and Ben Straub.

• Follow the conventional commit format
• Try to keep the subject line to 50 characters or less; do not exceed 72 characters
• Do not end the commit message subject with a period
• Use imperative mood in your commit message subject
• Add a single blank line before the commit message body
• Wrap the commit message body at 72 characters
• Do not use GitHub keywords or (@)mentions within your commit message
• Use the commit message body to explain the what and why of the commit

Follow the conventional commit format

The conventional commit format is a lightweight convention on top of commit messages. It provides an easy set of rules for creating an explicit commit history; which makes it easier to write automated tools on top of.

The commit message should be structured as follows:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

The type and description fields are mandatory, the scope field is optional. The body and footer are optional and can be used to provide additional context.

Find more information on the conventional commits website.

Try to keep the subject line to 50 characters or less; do not exceed 72 characters

The 50 character limit for the commit message subject line acts as a focus to keep the message summary as concise as possible. It should be just enough to describe what is being done.

The hard limit of 72 characters is to align with the max body size. When viewing the history of a repository with git log, git will pad the body text with additional blank spaces. Wrapping the width at 72 characters ensures the body text will be centered and easily viewable on an 80-column terminal.

Do not end the commit message subject with a period

This is primary intended to serve as a space saving measure, but also aids in driving the subject line to be as short and concise as possible.

Use imperative mood in your commit message subject

Imperative mood can be be thought of as a “giving a command”; it is a present-tense statement that explicitly describes what is being done.

Good Examples:

• fix: x error in y
• feat: add foo to bar
• Revert commit “baz”
• docs: update pull request guidelines

Bad Examples:

• fix: Fixed x error in y
• feat: Added foo to bar
• Reverting bad commit “baz”
• docs: Updating the pull request guidelines
• Fixing more things

Add a single blank line before the commit message body

Git uses the blank line to determine which portion of the commit message is the subject and body. Text preceding the blank line is the subject, and text following is considered the body.

Wrap the commit message body at 72 characters

The default column width for git is 80 characters. Git will pad the text of the message body with an additional 4 spaces when viewing the git log. This would leave you with 76 available spaces for text, however the text would be “lop-sided”. To center the text for better viewing, the other side is artificially padded with the same amount of spaces, resulting in 72 usable characters per line. Think of them as the margins in a word doc.

Do not use GitHub keywords or (@)mentions within your commit message

GitHub Keywords

Using GitHub keywords followed by a #<issue number> reference within your commit message will automatically apply the do-not-merge/invalid-commit-message label to your PR preventing it from being merged.

GitHub keywords in a PR to close issues is considered a convenience item, but can have unexpected side-effects when used in a commit message; often closing something they shouldn’t.

Blocked Keywords:

• close
• closes
• closed
• fix
• fixes
• fixed
• resolve
• resolves
• resolved

(@)Mentions

(@)mentions within the commit message will send a notification to that user, and will continually do so each time the PR is updated.

Use the commit message body to explain the what and why of the commit

Commits and their commit messages are the “permanent record” of the changes being done in your PR. Describing why something has changed and what effects it may have. You are providing context to both your reviewer and the next person that has to touch your code.

If something is resolving a bug, or is in response to a specific issue, you can link to it as a reference with the message body itself. These sorts of breadcrumbs become essential when tracking down future bugs or regressions and further help explain the “why” the commit was made.

Additional Resources:

• How to Write a Git Commit Message - Chris Beams
• Distributed Git - Contributing to a Project (Commit Guidelines)
• What’s with the 50/72 rule? - Preslav Rachev
• A Note About Git Commit Messages - Tim Pope

It’s OK to Push Back

Sometimes reviewers make mistakes. It’s OK to push back on changes your reviewer requested. If you have a good reason for doing something a certain way, you are absolutely allowed to debate the merits of a requested change. Both the reviewer and reviewee should strive to discuss these issues in a polite and respectful manner.

You might be overruled, but you might also prevail. We’re pretty reasonable people.

Another phenomenon of open-source projects (where anyone can comment on any issue) is the dog-pile - your pull request gets so many comments from so many people it becomes hard to follow. In this situation, you can ask the primary reviewer (assignee) whether they want you to fork a new pull request to clear out all the comments. You don’t HAVE to fix every issue raised by every person who feels like commenting, but you should answer reasonable comments with an explanation.

Common Sense and Courtesy

No document can take the place of common sense and good taste. Use your best judgment, while you put a bit of thought into how your work can be made easier to review. If you do these things your pull requests will get merged with less friction.

Trivial Edits

Each incoming Pull Request needs to be reviewed, checked, and then merged.

While automation helps with this, each contribution also has an engineering cost. Therefore it is appreciated if you do NOT make trivial edits and fixes, but instead focus on giving the entire file a review.

If you find one grammatical or spelling error, it is likely there are more in that file, you can really make your Pull Request count by checking the formatting, checking for broken links, and fixing errors and then submitting all the fixes at once to that file.

Some questions to consider:

• Can the file be improved further?
• Does the trivial edit greatly improve the quality of the content?

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

4 - Suggesting content improvements

If you notice an issue with the United Manufacturing Hub or one of its components, like the documentation, or have an idea for new content, then open an issue. All you need is a GitHub account and a web browser.

In most cases, new work on the United Manufacturing Hub begins with an issue in GitHub. UMH maintainers then review, categorize and tag issues as needed. Next, you or another member of the United Manufacturing Hub community open a pull request with changes to resolve the issue.

Opening an issue

If you want to suggest improvements to existing content or notice an error, then open an issue.

1. Go to the GitHub repository for the content you want to improve, like the main repository or the documentation repository.
2. Click Issues, then click New issue.
3. There are multiple issue templates to choose from. Choose the one that best describes your issue.
4. Fill out the issue template with as many details as you can. If you have a specific suggestion for how to resolve the issue, include it in the issue description.
5. Click Submit new issue.

After submitting, check in on your issue occasionally or turn on GitHub notifications. Reviewers and other community members might ask questions before they can take action on your issue.

How to file great issues

Keep the following in mind when filing an issue:

• Provide a clear issue description. Describe what specifically is missing, out of date, wrong, or needs improvement.
• Explain the specific impact the issue has on users.
• Limit the scope of a given issue to a reasonable unit of work. For problems with a large scope, break them down into smaller issues. For example, “Fix the security docs” is too broad, but “Add details to the ‘Restricting network access’ topic” is specific enough to be actionable.
• Search the existing issues to see if there’s anything related or similar to the new issue.
• If the new issue relates to another issue or pull request, refer to it either by its full URL or by the issue or pull request number prefixed with a # character. For example, Introduced by #987654.
• Follow the Code of Conduct. Respect your fellow contributors. For example, “The docs are terrible” is not helpful or polite feedback.