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:
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.
There's not much to worry about here. If you make a bad change, you can get back the original (last changed in your checked-out branch) version with e.g.
git checkout -- xml/decoderIndex.xml(Note the two dashes, and change the file path to the one you want changed back) Any changes you do make aren't recorded until you commit them, see below.
There are two things you should be careful of:
git add java/src/jmri/util/MyNewFile.javagit checkout -- to get back older
versions) but this can lead to you (accidentally) deleting other people's work. This is
Very Not Good. Don't copy files in and out of your repository space. If you're trying to do
something special, and you think that copying in and out is the only way to do it, ask for
help: There are ways of doing everything you want done without risking the loss of other
people's work.As you work, we encourage you to add a brief description of your changes to the draft release note, which can be found in the help/en/releasenotes directory as the help/en/releasenotes/current-draft-note.shtml file. When your changes are eventually merged into the main repository and included in a release, this will be how other JMRI users find out about them. You can also cut&paste what you write here into your pull request (see below) to help explain your change to the people reviewing it. If your work requires that the users be warned about something, i.e. to do a migration, please also add that to the help/en/releasenotes/current-draft-warnings.shtml file which works similarly.
With the older SVN system, 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 commitWhen 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.
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 git remote add yourname https://github.com/yourname/JMRI.git
(With the appropriate URL, changing "yourname" to your GitHub account name in three places)
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: (OK if it shows others or the order is different)
% git remote -v
origin https://github.com/JMRI/JMRI.git (fetch)
origin https://github.com/yourname/JMRI.git (push) yourname https://github.com/yourname/JMRI.git
git push
% git push
fatal: The current branch my-branch has no upstream branch.
To push the current branch and set the remote as upstream, use
git push --set-upstream origin my-branch
Just go ahead and do what it says:
git push --set-upstream origin my-branch
And occasionally, your local repository can be out of sync with your GitHub repository. If you get a message about "failed to push some refs" or similar, without specific commands to fix it, do (the first command here is why we created that remote with your name above; make sure it's there, and substitute your GitHub name in the first line):
git pull yourname(If any lines are flagged as conflicts, edit those to remove the conflicts, then "git add" them to resolve the conflict)
git commit -m "merging pull back" git pushIt is definitely easier to do this if you have no modified files in your repository, e.g. you've committed all your local changes.
Once your PR is merged, a git checkout master; git pull will bring it back
around to your repository and that cycle will be complete.
While all this is happening, you can work on something else by creating another branch and making changes there. But first, pick up the most recent contents of our central repository with:
git checkout master
git pull
Then you can create a new branch for a new project:
git checkout -b another-new-feature
just like you did at the start of this process, and continue to develop.
Approximately once a month, the contents of the master branch are taken and used to build a test release. These are announced to the user community to simultaneously make new features and fixes available, and to put the most recent code into wider use to flush out problems. The build process is documented separately. People are encouraged to download and use these, then report any problems via GitHub or the jmriusers group.
Approximately twice a year, a similar process is used to build production releases.
There's a group of people with "developer" status on the JMRI GitHub project who work more generally on JMRI code, for example taking on and resolving Issues opened by others. These people can assign Issues and PRs to themselves, and do a few other minor things. Typically, once somebody has solved a couple of Issues, they'll get an automated invitation to developer status from GitHub. These people are expected to be subscribed to the jmri-developers mailing list and to have public GitHub profiles that identify them.
A smaller group of JMRI "maintainers" on GitHub have the ability to edit, label and close all Issues and PRs, and to merge the contents of PRs to the main repository. This group does the infrastructure work that keeps the project code moving forward while avoiding unnecessary risk to the project's code and other assets.