Contributions to Sakai from all comers are welcome and encouraged.
Please use these guidelines and the information in README.md to assure that your contributions are compatible with our (evolving) workflow and practices.
The Sakai project participates in the Apereo Welcoming Policy.
Before a code submission will be accepted, you will need to submit a Contributor License Agreement (CLA). This is a one-off process that should only take a few moments to complete. See: https://www.apereo.org/licensing/agreements
To check the status of a CLA, please visit: http://licensing.apereo.org/
Bugs and features against Sakai are tracked in our JIRA instance and contributions must reflect a JIRA reference number in the messages and git branch names (e.g., SAK-29469), but please don't put these references in the code as over time files become full of them and the same information get be retrieved from git. To file or comment on a bug or feature, you will need a JIRA account.
Please take a look at our Confluence pages for pointers on getting started with Sakai development.
Generally when you make a change you will create a pull request that allows other people to examine the code and comment on the changes you've made. Typically you may get comments about:
You need to do some initial work to set your local environment. In the steps below, the following references are used:
clonethis repository on your workstation to make the local copy for everyday work)
To work on and contribute to Sakai:
Clone your origin repository onto your local workstation (this example uses HTTPS as the transport mechanism):
git clone https://github.com/GITHUBACCOUNTNAME/sakai
remote to receive updates from the upstream repository:
git remote add upstream https://github.com/sakaiproject/sakai
Update your local repository frequently to stay up to date:
git checkout master (switch to local
git pull upstream master (
pull in any upstream changes)
git push origin master (
push the changes up to the origin)
This branch should always be the same as what is in Sakai's upstream
master and if you make commits into your local
master, and those commits are not accepted into the Sakai master repository, you will forever be maintaining them yourself, which can get very complicated. To make life easier for yourself, use a branch for everything.
To fix a bug or add a feature, the general Git workflow is:
Create a local branch using JIRA reference for the branch name:
git checkout -b SAK-29469
Add changed or new files:
git add -u
Make your local commit:
git commit -m "SAK-29469 Add some documentation about contributing"
Share branch back to origin:
git push origin SAK-29469
Create a pull request (PR) using GitHub from the branch against the upstream
master for review by others
You will often receive friendly advice to improve or fix the changes you proposed in a p. To update your changes and maintain the existing PR, you should:
Change to your local branch:
git checkout SAK-29469
Make changes and/or improvements in response to PR comments
Add changed or new files:
git add -u
Update existing commit (this updates the previous commit rather than making a new one):
git commit --amend -C HEAD
Share your new local changes back to the origin branch and the original PR (by force is required for amending commits. You should only ever push by force into your own repo):
git push -f origin SAK-29469
Make a comment on the existing PR to alert reviewers to your changes
Security issues are typically handled differently than regular bugs to try to reduce visibility. To get a security fix into Sakai do the following.
More documentation and notes can be found in the Git Setup confluence page.
Questions are always welcome on the Sakai Developer mailing list. To join the list, send an email to email@example.com.