Checking Out the Tyrus Sources

Tyrus uses GIT version control system and this fact allowed us to have the project sources available on GitHub. The repository can be cloned in a read-only mode by invoking:

git clone git@github.com:tyrus-project/tyrus.git

If you’re only interested in reading the latest version of the sources and do not wish to a) contribute code back to the repository or b) do not care about the history, you can speed up the clone process by invoking:

git clone --depth 1 git@github.com:tyrus-project/tyrus.git

instead. This may speed up the clone process considerably.

Understanding Tyrus Branches and Tags

Tag & Branch information:

Tag/Branch Name Details
master This is effectively Tyrus development branch (“trunk” in SVN terms).
1.0 This is the Tyrus 1.0 release tag. A sustaining branch for Tyrus 1.0 release will be created from the tag if necessary. Fixed issues.
1.1 This is the Tyrus 1.1 release tag. A sustaining branch for Tyrus 1.1 release will be created from the tag if necessary. Fixed issues.
1.2 This is the Tyrus 1.2 release tag. A sustaining branch for Tyrus 1.2 release will be created from the tag if necessary. Fixed issues.
1.2.1 This is the Tyrus 1.2.1 release tag. A sustaining branch for Tyrus 1.2.1 release will be created from the tag if necessary. Fixed issues.
1.3 This is the Tyrus 1.3 release tag. A sustaining branch for Tyrus 1.3 release will be created from the tag if necessary. Fixed issues.
1.3.1 This is the Tyrus 1.3.1 release tag. A sustaining branch for Tyrus 1.3.1 release will be created from the tag if necessary. Fixed issues.
1.3.2 This is the Tyrus 1.3.2 release tag. A sustaining branch for Tyrus 1.3.2 release will be created from the tag if necessary. Fixed issues.
1.3.3 This is the Tyrus 1.3.3 release tag. A sustaining branch for Tyrus 1.3.3 release will be created from the tag if necessary. Fixed issues.
1.4 This is the Tyrus 1.4 release tag. A sustaining branch for Tyrus 1.4 release will be created from the tag if necessary. Fixed issues.
1.5 This is the Tyrus 1.5 release tag. A sustaining branch for Tyrus 1.5 release will be created from the tag if necessary. Fixed issues.

In order to check out a branch in git, you simply need to issue git checkout <branch name> (e.g. git checkout master).

If you’re interested in working with an existing tag, you’ll first need to issue git fetch --tags in order to obtain the tag references. After successful completion of this command, you can issue git checkout <tag name>. Note that when doing so, you’ll get a message about being in a detached state - this is normal and nothing to worry about. All fetched tags can be listed using git tag -l In general, we keep our tag names inline with the released version. For example, if you wanted to checkout the tag for Tyrus 1.0, the tag name would be 1.0 This convention is consistent for all branches/versions/releases.

Submitting Patches and Contribute Code

Contributing to Tyrus project can be done in various ways: bug fixes, enhancements, new features, or even whole new extension modules. In general, all contributions must comply with following requirements:

  • All contributors must sign the Oracle Contributor Agreement.

  • Any new contribution must be associated with an existing Tyrus issue. If no existing issue has been yet opened for the problem your contribution attempts to solve, please open a new one.

  • All bug fixes must be accompanied with a new unit test (or a set of unit tests) that reproduce the fixed issue.

  • New large feature contributions must be accompanied with:

    • A patch for Tyrus User Guide that is written in DocBook 5. Either a new chapter or a new section to existing chapter must be provided as appropriate.
    • At least one new example demonstrating the feature.

For small patches (minor bug fixes, correction of typos in documentation etc.), linking a gist that contains your patch with details on what you're resolving and how you've resolved it is most convenient approach. Alternatively, especially in case of larger contributions or more significant changes in code, please follow the process of opening a new GitHub pull request.

GIT Tips and Tricks for Developers

First, for anyone not familiar with Git, before attempting to work with the repository, we highly recommend reading the Git tutorial.

When collaborating, before you push your changes to the remote repository, it’s best to issue git pull --rebase This will ‘replay’ any changes that have occurred in the remote repository since your last pull on top of your current work. If you don’t do this, Git will perform a merge for you, however, the result of the commit will look like you’ve touched files that you haven’t. This is fine, but it generally raises a few eyebrows and makes code reviews of any patches slightly more complicated. As usual, more complications means more time spent in review.

There are times when you may need to move changes back and forth between branches. In cases where the code bases are very similar, you can use git cherry-pick <SHA1 of the commit to pick and apply> to do this quickly.

Back to top