Software documentation

Development tools

Structure

Techniques and Standards

How To

Functional Info

Background Info

JMRI: Developing with JMRI Code

Background

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

  1. You create a Git branch to hold your work.
  2. You periodically "commit" your changes to your local repository.
  3. You periodically "push" those changes to a repository of your own on GitHub.
  4. 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 Development

Git 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 pull
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 Repository

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


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

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


  git remote set-url --push origin https://github.com/yourname/JMRI.git
  
(With the appropriate URL)

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 Repository

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

  git push
  
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 Request

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