Most if not all open source projects [should] have a contributor guide, whose job is to explain the project policy and pace when it comes to accepting changes from the community. Indeed and among many other things, providing guidelines and documentation that teach one how to build, test and contribute patches of all sorts and colors is a pretty good sign of a healthy project and a vibrant community.

The overarching theme of this guide starts with the following questions:

1. What is the Apereo CAS project policy on accepting contributions?
2. How may one, seriously and in a step-wise fashion, get started with contributions?

What do I work on?

Certain number of projects in open source try to advertise work items and tasks which they think might be good candidates for contributions. This is generally and often not the Apereo CAS project policy. The policy is much simpler than that.

It goes something like this:

Everything is ideal for contributions.

In other words,

• There is no “We vs. You”.
• There is no “Some folks can only fix certain issues and some can’t”.
• There is no “Person X made the change; so X must fix it too” (aka code ownership)
• There is no “I am just a user; you are the developers”.

Of course, if you are a newcomer to the project and have just begun to understand the ins and outs of the CAS project codebase, there may certainly be areas in which you might find more comfort to slowly get your feet wet. You’re welcome to ask for suggestions. For the most part, the work item you wish to work on should be something you find interesting and enjoyable with some degree of practicality.

Remember that you are deploying open source software, which means you have automatically become a project/community member and a potential maintainer, whether you realize it or not. Staying in consume-only mode generally leads to poor results.

What can I work on?

All contributions are extremely welcomed with open arms regardless of shape, size and color. You may be interested in helping with fixing typos, writing documentation, authoring test cases, developing code, squashing bugs, etc. All is welcome.

More contributions simply equal more confidence.

In other words, if you happen to come across a bothersome use case and/or something you consider a perfect candidate for improvement and attention, you are most definitely, aggressively and wholeheartedly encouraged to spend time and DNA to improve the quality of your Apereo CAS life. There is no point in silent suffering.

If you find that contributing to the project is at the moment out of your reach, don’t worry. There are resources, here and here that can provide training and support to get you started for the win.

Do I need an issue first?

No.

If you have already identified an enhancement or a bug, it is STRONGLY recommended that you simply submit a pull request to address the case. There is no need for special ceremony to create separate issues. The pull request IS the issue and it will be tracked and tagged as such. Remember that this is open source software in an open and collaborative community. It’s not “Some folks report issues and some folks fix problems” software.

How do I report issues then?

You are welcome to submit issues via the project’s issue tracker. Someone will review the report and will try to evaluate whether this is a genuine RFE or defect in which case the issue will be closed with a follow-up request for contributions and patches.

The issue tracker is only a simple communication tool to assess a given problematic case or enhancement request. It’s not tracking anything, really. You are for the most part and at all costs encouraged to submit patches that fix the reported issue and remove pain, rather than waiting for someone to come along and fix it. As prescribed, there is no “we vs. you”.

Very simply put:

You are the one you have been waiting for.

But, can’t I just use the software?

The distinction between user and developer is, for the most part, an imaginary one in open source. You are not a user. You are not a developer. We all are contributors. If you have already diagnosed a problem or have found a use case for an attractive improvement and feature, we strongly recommend you simply walk down the path of making that all a reality and contribute back. If you find yourself unable to do so, you will need to find and procure resources that can teach you the how-to or do it for you. Reporting an issue and hoping/waiting for someone else to come along and provide a fix for you is never an acceptable strategy.

I am only one; but still I am one. I cannot do everything; but still I can do something; and because I cannot do everything, I will not refuse to do the something that I can do. - Edward Everett Hale

If you insist on being treated like a user, you then need to revisit and realign expectations with folks and resources that can provide you with the treatment you need. All of the work that goes into the development of a rich comprehensive software platform is almost exclusively done on a voluntary basis. Therefor, if you have expectations that resemble something of a commercial support agreement with clauses that include promises, guarantee, SLAs and follow-ups, you simply need to level up with an entity that actually provides that sort of functionality.

How do I know who’s working on what?

• Follow the WIP Pattern and submit early pull requests. This is in fact the recommended strategy from Github:

Pull Requests are a great way to start a conversation of a feature, so start one as soon as possible- even before you are finished with the code. Your team can comment on the feature as it evolves, instead of providing all their feedback at the very end.

Or put another way:

You’re opening pull requests when you start work, not when you’re finished.

There is of course the alternative: ask.

Can I backport a change to a maintenance branch?

Yes, absolutely. Provided the change fits the scope of the maintenance branch and its tracking release and assuming the branch is still under care, you are more than welcome to move changes across the codebase various branches as much as needed to remove pain and improve.

What if the change is too big?

Start by reviewing the release policy. The change you have in mind should fit the scope of the release that is planned. If needed, please discuss the release schedule and policy with other community members to find alternative solutions and strategies for delivery.

Is it worth it?

The CAS project generally operates based on its own maintenance policy. Before making changes, you want to cross check the CAS deployment you have today and ensure it is still and to what extent considered viable and maintained by the project.

How do I get on the roadmap?

By simply delivering the change and having it get merged into the codebase relevant branches. There is no predefined roadmap for the project. The roadmap is what you intend to work on. Work items get completed based on community’s availability, interest, time and money.

Practically, how soon is that exactly?

You can review the release schedule from here. Note that the dates specified for each are somewhat tentative, and may be pushed around depending on need and severity.

As for general contributions, patches in form of pull requests are generally merged as fast as possible provided they are in good health. This means a given pull request must pass a series of automated checks that examine style, tests and such before it becomes eligible for a merge. If your proposed pull request does not yet have the green marking, worry not. Keep pushing to the branch that contains your change to auto-update the pull request and make life green again.

If you find that the project is not moving forward at a pace you find reasonable, simply ping the pull request and gently remind someone to step forward and review the issue with you.

How do I do this?

There is the contributor guide, for sure. However, in this section we are going to practically take a look at the entire process from start to finish and see the patch all the way through.

In order to successfully finish this exercise you need:

1. Git
2. IntelliJ IDEA, eclipse or NetBeans (Depending on the change, vim may be perfectly fine too)
3. Java (JDK)

Fork the repository

First thing you need to do is to fork the CAS repository under your own account. The CAS repository is hosted on Github and is available here.

Clone repositories

There are much faster ways of cloning the codebase, but let’s keep it simple for now:

git clone git@github.com:apereo/cas.git
cd cas
git remote add mmoayyed git@github.com:mmoayyed/cas.git
git checkout master

Next, if you simply list the remotes you should see:

origin  git@github.com:apereo/cas.git (fetch)
origin  git@github.com:apereo/cas.git (push)
mmoayyed  git@github.com:mmoayyed/cas.git (fetch)
mmoayyed  git@github.com:mmoayyed/cas.git (push)

You want to isolate your changes inside individual topics branches and never commit anything to the master branch. The workflow more or less is the following:

1. Create topic branch.
2. Make changes and test.
3. Commit changes to branch.
4. Go back to #2 until you are satisfied.

Create branch

To create a topic branch for the change, execute:

git status
git checkout -b my-topic-branch-which-fixes-something

Commit changes

When you’re ready to commit changes after having made changes, execute:

git add --all && git commit -am "This change fixes a problem"

Note that the --all flag adds all modified files in the project directory. If you wish to pick and choose, you can either individually add files via a git add fileName command one at a time or perhaps, it might be best to simply opt for a GUI client such as SourceTree or Git Extensions.

Push changes

Push your changes from the local branch to a remote branch of your own fork:

git push mmoayyed my-topic-branch-which-fixes-something

Submit pull request

Follow the guide here to create a pull request based on your branch to the CAS project. In this particular case, the target branch is the master branch because your own branch was created off of the master branch.

How fast can I consume the change?

SNAPSHOT releases are published by the automatic Travis CI process. As soon as a patch is merged, you want to track its build status and once it turns green, you should be good to update snapshots in your build script. Practically, this process can take up to 50 minutes or less. Refer to the README file of the build script and the project documentation to learn how you may update the overlay to take advantage of the change.

This practically usually involves running the build with a -U or --refresh-dependencies command for Apache Maven and Gradle respectively.

So…

I hope this brief overview was of some assistance to you. If you happen to come across other ideas that would make all our CAS lives easier, by all means and without hesitation, please get involved.

Misagh Moayyed