Bob-the-Kuhn thinkyhead

Contributing Code with Pull Requests

Introduction

GitHub is a great tool for collaboration, but it has a bit of a learning curve. The power of GitHub comes from the Git version control system. Git will be familiar if you’ve used other version control systems like CVS, Apache Subversion, or Mercurial. GitHub adds helpful collaboration features that make it an ideal platform for maintaining the Marlin project.

Before submitting code and other content, please review Contributing to Marlin and Marlin Coding Standards. Following our guidelines ensures that your changes will be accepted more quickly.

Set up GitHub, Fork, and Clone

Before you can contribute to Marlin, you need to get a free GitHub.com account. This is a pretty quick process. Please upload a unique icon or image so it will be easier to identify you on the project pages! You’ll also need to download and install the GitHub Desktop application.

After signing in to your GitHub account, go to the main Marlin repository at: https://github.com/MarlinFirmware/Marlin and create a fork of Marlin by clicking the fork icon in the top right of the page.

image1

When GitHub is done copying files, a page will appear displaying your shiny new fork of Marlin. This takes about 10-20 seconds, so be patient. You may need to wait for the Fetching Latest Commit message to go away also. If it still hasn’t finished after few minutes then GitHub might be hung up (not unusual).


It’s always best to leave the repository name as “Marlin” unless you plan to make your own custom version of Marlin for publication. Here are the instructions if you want to rename it.

Click on the Settings icon.

image2

Click in the Repository name box, type the new name, and click Rename.

image3

image4

This takes you back to your fork’s main page, where the new name is displayed.

Edit the title by clicking Edit.

image5

Type in the new title and click Save.

image6


Change the Default Branch

At this time we’re using the bugfix-2.1.x branch to patch bugs for the next minor release, and we’ll create a new branch for the next major release as we develop a plan. We recommend you change the “Default Branch” in your fork to bugfix-2.1.x to make it easier to do Pull Requests later.

Click on the branches tab to view all branches in your fork.

image8

Click on the Change default branch button.

image9

Click on the branch dropdown button. Select bugfix-2.1.x and click Update.

image10

A warning pops up. Just click the button.

image11


Clone Marlin to GitHub Desktop

Click the “<> Code” tab

image12

Click the Clone or download button

image13

Select Open in Desktop

image14

A security popup may appear. Just click the Allow button

image15

Click OK to save it in the default location.

image16

A progress bar appears.

image17

Using GitHub Desktop…

You now have a “working copy” of Marlin. Note that only the branch you selected on your GitHub page may have been downloaded. Check that the desired branch was downloaded by clicking on Changes.

image18

Click Open this repository.

image19

A Windows Explorer window appears. Open the Marlin directory and then open the Version.h file.

image20

Scroll down until the #define SHORT_BUILD_VERSION is visible. The text should be “bugfix-2.1.x.”

image21

If you downloaded the wrong branch, go back to the GitHub website, select the correct branch, and choose “Open in Desktop” again.


Make a feature branch

It’s a good idea to keep an unaltered copy of the bugfix-2.1.x branch that you keep in sync with the main repository. Before editing any code you should make a copy of bugfix-2.1.x and give the new branch a descriptive name.

image22

Make a new branch via Desktop by clicking this icon:

image23

Type in the branch name and click Create new branch.

image24

The new branch is automatically selected. Click the Publish button to upload the branch to your fork on GitHub. (The button changes to Sync once the branch has been published.)

image25


Make Changes and Test

You can freely edit code files, configurations, etc., in your working copy. You can make new branches in your working copy to experiment, then throw them away. Nothing counts until you publish and sync your changes. And thanks to the magic of git you can always go back to earlier points in time.

In the main view, GitHub Desktop shows all your uncommitted changes in a list. You can click on each item to see the specific changes in the right pane. Previous commits are shown under the “History” tab.

Commit to your Working Copy

Use GitHub Desktop to “commit” the changes you want to keep (to your working copy). A commit stores your changes and provides a “bookmark” (Commit ID) for the point in time when the changes were committed. The “commit message” summarizes why the changes were made.

Tick the checkboxes on all the files that you want to commit. (Note that you can also “cherry-pick” selected changes by clicking in the margin of the second pane.)

image26

Fill in the Summary and Description, then click Commit. Voila! The selected changes are packaged and ready for submission.

image27

Once everything is committed, publish to your GitHub account by clicking the Sync button:

image28


Submit code with a Pull Request

Before submitting the Pull Request:

Submit from GitHub Desktop

You can use GitHub Desktop to submit a Pull Request by using the Pull Request button, but you must be careful to specifically target the MarlinFirmware/bugfix-2.1.x branch!

Submit from the GitHub website

Return to your fork’s page on GitHub, select your updated branch, and click the New Pull Request button.

image29

GitHub should automatically detect the target for the Pull Request as bugfix-2.1.x in the main MarlinFirmware project. However, you may instead see a page like the one below. In that case, click the Compare across forks button:

image30

To target the bugfix-2.1.x branch in the main Marlin repository, click the base button and select bugfix-2.1.x. (For new features you should instead use dev-2.1.x.)

image31

Click compare across forks (again).

image32

Click on the head fork: button and then click on your repository.

image33

Click on the compare button and then click the name of the branch you created with Desktop.

image34

If you have only a single commit, its text will be copied into the Pull Request. Edit as needed to provide all the relevant details. When your description is complete click the Create Pull Request button.

image35

Here’s the Pull Request that was just created.

image36

If you have an open issue associated with your Pull Request, include that issue’s number in your Pull Request description (e.g.,#1536”), and a link to the Pull Request will automatically appear on the issue’s page. The same goes for individual commit descriptions.

Updating the PR

Typically you’ll get requests to correct, improve and add features to your code. The top level steps of doing this are:

  1. Open your branch in Windows Explorer
  2. Edit & test your code
  3. Apply the code to the PR (commit & sync)
  4. Repeat 1-3 as necessary
  5. Resolve “All checks have failed” issues
  6. Make the PR pretty & sync to main repository ( may need to be done multiple times)

Open your branch in Windows Explorer

You’ve done most of this before when you created your branch.

Open Desktop, select your repository (on the left side), select your branch (top left), click on Changes (top middle) and then click on open this repository (right middle)

image37 A Windows Explorer window will popup. Copy the Marlin directory to your work area. Close the Windows Explorer window and close Desktop.

image38

Edit and Test

As before, do all your work & testing in your local copy.

Move the code to the PR (commit & sync your code)

Open Desktop and the Windows Explorer window as before

Copy the changed files into the new Windows Explorer window. Alternatively you can just copy your entire directory over. GitHub will check the newly copied files against the old and only list the ones that have changed.

Finish the commit and Sync as you did previously in Commit changes to your working copy.

When a branch is associated with a PR, the PR is updated on every Sync.

Most of the time you’ve made changes to the Configuration.h and Configuration_adv.h files that are specific to your printer. Do NOT upload those to the PR. This can be done multiple ways:

  • Don’t copy them into the GitHub directory
  • Don’t include them in the commit

Repeat the above as necessary

Resolve “All checks have failed” issues

When you create a PR (and every time you commit new code) GitHub uses the “Travis CI” service to run several tests on the code by enabling various combinations of options and compiling for various target platforms. Any failed tests need to be resolved before the PR can be merged into the main Marlin repository.

Within 30-90 seconds of doing the sync the PR will have a section that looks like this:

image39

Several minutes later the PR will show this status if there are no problems:

image40

If you see a “failed” status instead then something needs to be fixed. You don’t have to fix the PR immediately but it must be fixed before it can be merged into the main Marlin repository.

To see the errors click on Details

image41

This will bring up the Travis log. Green means that the test has passed. Red means there’s a problem.

image42

It’s recommended that you include the fixes in the next code you commit.

The errors you’re looking at come from the compiler. Resolve just like you do when compiling on your local machine.

Unfortunately the Travis log does not include the options that were enabled when the errors were found. That makes it harder to reproduce the problem locally.

Organize and Sync the PR

If you’ve made a lot of small fix-up commits it can be hard to see the combined result. So before a PR is merged it’s helpful to reduce your commits down to a manageable number and get them organized. They can even be combined into a single commit.

This process also incorporates any code changes in the main Marlin code that have been done since the PR was created or the last time the process was run.

This process uses a command window (shell) to issue GIT commands.

Open Desktop and open the Windows Explorer window. Make a copy of the directory. You may need it later.

Next, right-click on the repository to open the popup menu. Select Open in Git Shell.

image43

The Git Shell will open.

image44

Type git remote –v into the Git Shell and press return to execute the command.

image45

If the upstream remote is missing then type git remote add upstream https://github.com/MarlinFirmware/Marlin.git followed by return.

Next type git fetch upstream followed by git rebase upstream/bugfix-2.1.x. If the rebase succeeds the output will look like this:

image46

If Git can’t automatically merge the code then it’ll look like this.

image47

This tells you the number of files that need to be examined and the names of the files. In this example there’s only one file needing attention.

Git marks conflicts within the file and then writes the modified file to the directory you opened with Desktop.

Open the modified file (the file name didn’t change but the timestamp did) and search for <<<<<<< HEAD. This marks the beginning of the code that could be newer than what you started with. The ======= marks the boundary between the newer code and the original code in your file. The >>>>>>> line marks the end of the conflicting code. In this example, “#endif in wrong place” is the title of the commit that GIT couldn’t automatically handle.

Resolving conflicts is a bit of an art, and it may take some practice to start getting a feel for what’s going on. Often it may be helpful to consult the copy you made just before opening the Git Shell. It may help to keep the latest bugfix-2.1.x on GitHub open in the browser as a reference on what to keep and what to change.

image48

Save the file.

Go to Git Shell and enter the command git rebase --continue. This will tell git to keep your changes and continue with the rebase.

image49

Repeat the edit-save-add-commit cycle until all the files have been committed.

If you couldn’t address all the files then you can abort the process with: git rebase –abort

If all the files have been addressed then enter this into the Git Shell: git rebase –continue

The next step is to “squash” the commits using an interactive rebase. This allows you to easily combine commits together. To start the process enter the command: git rebase -i upstream/bugfix-2.1.x.

Assuming there are no conflicts, an editor window should open with a list of your commits. Each line begins with the action you want performed, which is pick by default. You may see extra commits if the main code base has been updated, so make sure the commits are all yours. Change the action to drop for any commits you don’t want to keep. Your first commit should be left as pick (or reword if you want to change the commit message). Set the action to fixup (or just f) for any commits you want to combine with the pick commit that precedes it.

image50

After making all necessary changes, save the file.

image51

In a few seconds a second editor window will pop up. Here you can provide a description for the squashed commit.

All lines without a leading # will be included the description. Edit the description to itemize the combined changes, then save and close the file.

image52

After saving and closing the editor, the Git Shell will show this:

image53

In Git Shell type git push –f to push the changes to your fork on Github. Check the output to make sure it succeeds.

image54

You can now close Git Shell.

In Github Desktop you should see that only the commits you picked are left, and all your fixups are now part of those commits.

You won’t need to click Sync in Desktop at this point because you already used push -f.

You can now close Desktop and the Windows Explorer window you opened from Desktop.