We want to start off by saying thank you for using CAS. This project is a labor of love, and we appreciate the work done by all who catch bugs, make performance improvements and help with documentation. Every contribution is meaningful, so thank you for participating. That being said, here are a few guidelines that we ask you to follow so we can successfully address your patch.
The goal of this guide is to, very simply put, help you learn how to catch fish.
Shed all of your fears of making a mistake as part of your contributions to the project. Practice makes perfect and we are all here to help you as much as we can so you can ultimately become an independent contributor to the project. It’s OK to make mistakes and it does take some time, effort and energy to improve the state of proposals and contributions. So do not be discouraged, keep at it and if you find anything that is unclear along the way, do not hesitate to ask questions.
The overarching theme of this guide starts with the following questions:
- What is the Apereo CAS project policy on accepting contributions?
- 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.
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.
Do I need an issue first?
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. 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.
If you’d rather just report the issue to have others benefit from your discovery, it would be best if you could share the use case and the problem at hand via community mailing lists, chatrooms and the likes of StackOverflow.
What if I am not a developer?
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. Talk to your institution, company, organization, supervisor, boss, mentor, architect, manager, director, CIO, CTO, CISO, etc and have them procure the right resources for the job.
Reporting an issue and hoping/waiting for someone else to magically come along and spend time, money and energy to provide a fix for you is never an acceptable strategy. Quit waiting for the light at the end of the tunnel and light it yourself.
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.
I have an idea; It would be nice if…
It would be nice. No, it would be fantastic, superb, marvelous and ultra great. Please consider that lone ideas by themselves are more or less pointless unless they are executed and realized in concrete form. There is no shortage of ideas; good or bad. There is a shortage of folks who are ready and serious enough to execute and deliver the idea. This is very much a call to action and one that allows you to graduate from a think-tank into a doer, a contributor, a promoter and a leader. If you consider something to be worth doing, a very best thing you can do is to demonstrate concretely and seriously, that it is, in fact, worth doing. Doing something about an issue or request does not necessarily equal to you, the individual contributor, writing code. That is only one of many possible options. We hope that you consider that as a good starting place and when all else fails, consider reaching out for support.
I found a problem. Should I…?
Yes, you should. If you find something that you consider to be odd, wrong or wobbly behavior and have found an alternative solution that removes the obstacle or delivers the case, please consider reporting and sharing that improvement in form of a patch to the project so it can be discussed and potentially accepted. There is no down-side to this, as you engage and collaborate with community members concretely and in action; It is quite possible that they may have found a better solution and might be able to share that with you for longer prosperity. Be not afraid; the worst that could happen is someone stepping up to help you out with better options.
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.
How frequently should I make progress?
If you do have a pending pull request available and one that might also be tagged as WIP, you are most welcome to keep pushing to the underlying branch as frequently as you prefer. There is nothing spammy or annoying about making progress on a WIP pull request. Nobody is going to get mad at you for making progress and pushing changes, (That’s what email filters, etc are for), so do not ever worry about annoying other contributors and/or project members with the frequency of your progress notifications. Continue working on the use case as often as you like and be sure to keep asking for feedback as you make progress.
Note that contributions and pull requests that remain inactive for a certain period of time get tagged as Pending and will be eventually closed automatically. Staleness is only allowed to a certain degree, but worry not. Any stale closed pull request can always be reopened and progress resumed without data loss.
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.
Remember that changes applied to previous branches that target CAS versions in maintenance mode MUST be ported forward to the master branch as well, via a separate pull request.
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. Work items get completed based on community’s availability, interest, time and money. The roadmap is what you intend to work on.
How often are changes released?
You can review the release schedule. Note that the dates specified for each milestone 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 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
--refresh-dependencies command for Apache Maven and Gradle respectively.
Why isn’t my proposal accepted and merged yet?
Patches submitted to the codebase in form of pull requests are generally reviewed as quickly as possible and most are often accepted. If you find your contribution to take longer than usual to be merged, it’s possible that the proposed changeset violates one or more of the following principals:
- The patch fails to pass automated unit or integration tests.
- The patch fails to adhere to the project’s styleing guidelines.
- The patch fails to provide adequate unit or integration tests for the proposed changes.
- The patch fails to provide an explanation or objective for the proposed changes.
- The patch has remained stale for quite a while without any sign of contributor activity.
- The patch modifies system behavior without consensus, collective feedback or internal validation as unit or integration tests.
- The patch modifies a large number files, more than one could practically review in a timely manner.
- The patch presents a feature or behavior that is deemed too specialized or custom with unwarranted assumptions.
- The patch introduces (i.e. formatting) changes that are not related to the proposal’s objective.
- The patch violates the general design principals of the codebase or introduces inconsistent or contradictory concepts that would be difficult to maintain.
If you need help, please ask and seek clarification as often as you prefer. The shared objective of a pull request is not to judge or point fingers, but to collaborate together and make progress. Remain positive, optimistic with a healthy attitude towards comments and constructive feedback.
There may be accidental mistakes or infrastructure mishaps along the way. You’re most welcome to ping the pull request and provide an explanation and/or comment. In most, if not all, cases the patch is accepted.
Before you do anything else, make sure you have a functional build.
How do I do this?
In order to successfully finish this exercise you need:
- IntelliJ IDEA, eclipse or NetBeans (Depending on the change,
vimmay be perfectly fine too)
- Java (JDK)
Fork the repository
There are much faster ways of cloning the codebase, but let’s keep it simple for now:
1 2 3 4 git clone --recursive firstname.lastname@example.org:apereo/cas.git cd cas git remote add github-username email@example.com:github-username/cas.git git checkout master
Next, if you simply list the remotes you should see:
1 2 3 4 origin firstname.lastname@example.org:apereo/cas.git (fetch) origin email@example.com:apereo/cas.git (push) github-username firstname.lastname@example.org:github-username/cas.git (fetch) github-username email@example.com:github-username/cas.git (push)
You can use
git submodule update --init --recursive to fetch all submodules linked to the repository.
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:
- Create topic branch.
- Make changes and test.
- Commit changes to branch.
- Go back to #2 until you are satisfied.
You may want to ensure the codebase can be built locally from source. Follow this guide to learn more.
To create a topic branch for the change, execute:
1 2 git status git checkout -b my-topic-branch-which-fixes-something
When you’re ready to commit changes after having made changes, execute:
1 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 your changes from the local branch to a remote branch of your own fork:
1 git push github-username 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
The CAS codebase dedicates specific branches to feature and major releases of the software (i.e.
6.0.x, etc). These branches will continue to live on in maintenance mode until the release is declared EOL and form the basis of follow-up patch releases and maintenance cycles. When you are preparing a pull request, please be sure to select the appropriate target branch for the patch to ensure your change can be included in the coming maintenance release as scheduled.
Once more, please remember that changes applied to previous branches that target CAS versions in maintenance mode MUST be ported forward to the master branch as well, via a separate pull request.