JMRI: Developing with JMRI Code
BackgroundAnybody is welcome to get a copy of the JMRI code and modify it for their own purposes. What makes one a JMRI developer is contributing those modifications back for others to use. This page discusses how to do that, assuming that you've gotten a copy of the code following the previously described procedures.
See the JMRI Git FAQ page for more details on these processes.
The links to the left provide more information on building with specific tools. You should read the page for your particular setup.
The rest of this page provides an overview of the process of developing JMRI code with Git. Basically, you create a new branch, make your changes, compile/run/test until you've finished your intended change, and then send that change back for inclusion into the main repository.
That's done with a four-step process:
- You create a Git branch to hold your work.
- You periodically "commit" your changes to your local repository.
- You periodically "push" those changes to a repository of your own on GitHub.
- When your change is complete, you create a "pull request" that allows JMRI to get your change from your GitHub repository and merge it into JMRI's main repository.
Create a Branch for DevelopmentGit is very good at keeping development on parallel "branches" separate. Although the primary development is on the "master" branch, we strongly recommend that you don't directly make changes to that. There are a lot of JMRI developers, and having them all work on a single branch can get confusing. Instead, you should create a separate branch for each of your projects, work on it until it's ready to be merged back into the main JMRI source, and then contribute the entire branch contents back to our main repository.
To create a new branch:
git checkout master
git checkout -b my-new-feature-or-fix
The first two "git checkout master" & "git pull" lines makes sure that you are starting from the most recent "master" branch contents. The master branch is where we do development between test releases.
The -b option in the last line creates a new branch which will contain your new work. This lets you work on it without interference from other people's changes until you're ready to merge with those. The "checkout" means that you're now working on that new branch, which will hold whatever you commit in later steps.
Commit Changes to Your Local RepositoryYou should commit your changes into your local repository often.
With SVN, there was one central repository that everybody shared. Git provides everybody with their own local repository, and then links them together with "pull", "push" and "pull request" operations. When you commit, you're saving a copy of your changes into your local repository where they're safe, and can eventually be moved onward.
When you do this, Git will open an editor window for your commit note. The top line becomes the summary, which should be clear by itself as this will appear in lists of changes. You should keep that summary to 50 characters or less, so it can be displayed compactly. Please add more detail in additional lines after the summary, because that helps your friends and colleagues understand what you've done.
Get Your Own GitHub Repository
- Get a GitHub account and login
- Tell GitHub to "fork" JMRI's repository into one of your own. There's a good help page, but basically you go to the JMRI repository page and click the "fork" button in the upper right.
This gives you your own repository, which you can then work with freely.
If you're using the command line, the next step is to connect it to your local repository. (IDE users will do this next part in their IDE, see those instructions) On the web page for your repository, right side, is a "HTTPS Clone URL". Copy that. In your repository directory on your local computer, do
(With the appropriate URL)
git remote set-url --push origin https://github.com/yourname/JMRI.git
After this, doing a "git push" will push your changes up to your repository. "git pull" will still pull from the main repository so that you can get the most recent updates from others. To check this, do a "git remote -v" which should show:
% git remote -v
origin https://github.com/JMRI/JMRI.git (fetch)
origin https://github.com/yourname/JMRI.git (push)
Push Your Changes to Your GitHub RepositoryNow that you have a consistent set of changes committed locally, you can move them up to your repository on GitHub. That makes them visible to everybody else.
Sometimes, git will tell you that you need a more complicated push comment, with some options that start with - or --. Just copy and paste that line to execute it.
Submit a Pull RequestThe last step is to make your changes, already visible in your GitHub repository, known to the JMRI maintainers so that one of them can pull it into the main JMRI repository. To do that, you create and submit a "pull request" that automatically has all the needed info.
- Login to GitHub and go to the page for your JMRI clone repository (yours, not the main JMRI one)
- There's a "Pull Request" button at the upper right of the file listing. Click it.
- On the next page, select the branch you've been working on and click the "Create pull request" button.
- Fill out the forms. A short title that describes the feature you've written helps other people find it. A few lines in the comment about what it does, how you added it, etc is also very helpful.
- Click "Create pull request". That submits all the info, starts the Continuous Integration (CI) tests and notifies the JMRI maintainers.
- One of the maintainers will check over your code and the test results, and then either contact you for more info (occasionally), or merge it into the master branch in the the main repository (more often). You can sign up for a notification when that happens.
- Sometimes, a maintainer will put a label on your PR
to indicate its status. Some of the more interesting ones are:
- "WIP" - this is a "blue flag" indicating Work In Progress - something is needed before this can be merged in. Place it on a PR so that maintainers don't have to read the entire thread before doing the merge.
- "After Next Test Release" and "After Next Production Release" - placed when a PR should be merged later for some reason
- "Add To Next Release" - needs to be merged before the next release is built
- "dev/test/publish infrastucture" - there's a lot of automation around building and publishing JMRI. This change is to that infrastructure, not the released JMRI code itself.
- "Cleanup" - a change that improves the code, but doesn't really affect JMRI users directly
- "Support Request" - A request for help figuring something out, typically found in the Issues section. Typically these items are closed if resolved, or become "Enhancement" or "Bug" items.
- "Enhancement" - request that somebody make JMRI better in some way.
- "Bug" - a problem that's bitten at least one person.
- "Duplicate", "Invalid", "Won't Fix" - items that have (typically) been closed without action. Issues and PRs never go away, but these labels mark them as not intended for further consideration.