Contributing Code with Pull Requests
The current version of this document is targeted at Windows users.
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.
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.
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).
Rename your Fork (not recommended)
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
Click in the
Repository name box, type the new name, and click
This takes you back to your fork’s main page, where the new name is displayed.
Edit the title by clicking
Type in the new title and click
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.
Click on the
Change default branch button.
Click on the branch dropdown button. Select
RCBugFix and click
A warning pops up. Just click the
Clone Marlin to GitHub Desktop
Clone or download button
Open in Desktop
A security popup may appear. Just click the
OK to save it in the default location.
A progress bar appears.
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
Open this repository.
A Windows Explorer window pops up. Open the
Marlin directory and then open the
Scroll down until the "#define SHORT_BUILD_VERSION" is visible. The text should say RCBugFix in it.
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.
Make a new branch via Desktop by clicking this
Type in the
name and click
Create new branch.
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.)
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.)
Fill in the
Description, then click
Commit. Voila! The selected changes are packaged and ready for submission.
Once everything is committed, publish to your GitHub account by clicking the
Submit code with a Pull Request
Before submitting the Pull Request:
- Please review the Marlin project guidelines.
- Make sure you’ve compiled and done some sanity tests on the code.
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
Submit from the GitHub website
Return to your fork’s page on GitHub, select your updated branch, and click the
New Pull Request button.
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:
To target the
RCBugFix branch in the main Marlin repository, click the
base button and select
compare across forks (again).
Click on the
head fork: button and then click on
Click on the
compare button and then click the
name of the branch you created with Desktop.
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.
Here’s the pull request that was just created.
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.