Bob-the-Kuhn thinkyhead

Contributing Code with Pull Requests


The current version of this document is targeted at Windows users.

Intro

GitHub is a great tool for collaboration, but it takes some getting used to. The power of GitHub centers around the git version control system. If you’ve used version control systems like CVS, Subversion, or Mercurial, then git should be familiar. GitHub provides issue management, bug tracking, and other features that make it an ideal platform on which to build Marlin and its associated content.

Before submitting code and other content, please review Contributing to Marlin and Marlin Coding Standards. These pages are still on the old wiki, but we’ll publish them here soon.


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

RCBugFix is the work branch for our next release. For convenience you may want to change the “Default Branch” to RCBugFix in your fork 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 RCBugFix and click Update.

image10

A warning pops up. Just click the button.

image11


Clone Marlin to GitHub Desktop

Click on <> Code

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 on your PC. 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 pops up. 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 say RCBugFix in it.

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

You should keep an unaltered copy of the RCBugFix branch that you can keep up to date from the main project. To make patches or add a new feature, make a copy of RCBugFix with a descriptive name.

image22

Make a new branch via Desktop by clicking this icon:

image23

Type in the name and click Create new branch.

image24

The new branch will be automatically selected. Click the Publish button to make a copy on GitHub. (The button changes to Sync once the branch is published to your account.)

image25


Make code changes & 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 changes to your working copy

Use GitHub Desktop to “commit” (in your working copy) the changes you want to keep. A commit not only stores your changes but also acts like a bookmark for the point in time when the changes were committed. Each “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/RCBugFix 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 RCBugFix 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 RCBugFix branch in the main Marlin repository, click the base button and select RCBugFix.

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.