Skip to main content

​
Getting Started

​
Code of Conduct

Sakai participates in the Apereo Welcoming Policy.

​
Contributor License Agreement

Before any code submission will be accepted, you must submit a Contributor License Agreement (CLA). This is a one-time process.
1

Submit CLA

Complete the CLA at: https://www.apereo.org/licensing/agreements
2

Check CLA Status

Verify your CLA status at: http://licensing.apereo.org/

​
JIRA Issue Tracking

All bugs and features are tracked in Sakai JIRA.

​
Creating an Issue

1

Create JIRA account

Sign up for a JIRA account to file and comment on issues.
2

Search for existing issues

Check if the bug or feature already exists before creating a new issue.
3

Create new issue

Provide:
  • Clear title and description
  • Steps to reproduce (for bugs)
  • Expected vs actual behavior
  • Sakai version affected
  • Screenshots if applicable
4

Note the issue key

You’ll need the issue key (e.g., SAK-12345) for your branch and commits.
Include JIRA references in git branches and commit messages, but not in code comments. Use git history for this information instead.

​
Git Workflow

​
Initial Setup

Set up your Git environment:
1

Configure Git

git config --global user.name "Your Name"
git config --global user.email "[email protected]"
2

Fork the repository

Fork sakaiproject/sakai to your GitHub account.
3

Clone your fork

git clone https://github.com/YOUR_USERNAME/sakai.git
cd sakai
4

Add upstream remote

git remote add upstream https://github.com/sakaiproject/sakai.git

​
Keep Fork Updated

Never work directly in your local master branch. Always create feature branches.
Regularly sync your fork: 
git checkout master
git pull upstream master
git push origin master

​
Creating a Pull Request

​
Single Issue per Pull Request

Most pull requests address a single issue:
1

Create branch

Use the JIRA key as the branch name:
git checkout -b SAK-12345
2

Make changes

Write your code, following the Code Style Guidelines.
3

Add files

git add -u
4

Commit with proper message

Format: <issue key> <component> <brief description>
git commit -m "SAK-12345 Assignments add option x when creating an assignment"
5

Push to your fork

git push origin SAK-12345
6

Create pull request

Go to GitHub and create a pull request from your branch to sakaiproject/sakai:master.
7

Merge strategy

When merged, maintainers will use Squash and Merge.

​
Multiple Issues per Pull Request

Sometimes related issues are best addressed together:
1

Create branch

git checkout -b SAK-12345
2

Make changes for first issue

Write code for the first issue.
3

Commit first issue

git add -u
git commit -m "SAK-12345 Assignments add option x when creating an assignment"
4

Make changes for second issue

Write code for the second issue.
5

Commit second issue

git add -u
git commit -m "SAK-23456 Assignments add option y when creating an assignment"
6

Push all commits

git push origin SAK-12345
7

Create PR mentioning all issues

Mention all issue keys (SAK-12345, SAK-23456) in the PR description.
8

Merge strategy

When merged, maintainers will use Rebase and Merge to preserve individual commits.

​
Pull Request Reviews

Your PR will be reviewed for:
  • Matches existing code style in the file
  • Follows Sakai coding standards
  • Uses kebab-case for HTML class/id attributes
  • Maintains consistent format (tabs/spaces)
  • Aligns with surrounding code
  • All user-facing strings are externalized
  • Supports multiple languages
  • Uses resource bundles correctly
  • Follows WCAG 2.0 AA standards
  • Semantic HTML used
  • ARIA labels where appropriate
  • Keyboard navigation works
  • Sensible solution to the problem
  • No obvious performance issues
  • Uses appropriate Sakai APIs
  • Follows architectural patterns
  • Only modified lines needed for fix/feature
  • No bulk reformatting
  • No unrelated changes
  • Addresses one issue (or closely related issues)
  • Focused scope
  • Tests passing
  • New tests added where appropriate
  • E2E tests for UI flow changes
  • Linked to JIRA issue
  • Explains why, not just what
  • Clear and concise

​
Responding to Feedback

Update your PR based on review comments:
1

Switch to your branch

git checkout SAK-12345
2

Make requested changes

Update code based on feedback.
3

For single-issue PRs (Squash and Merge)

Create a new commit:
git add -u
git commit -m "Updated per review comments"
git push origin SAK-12345
4

For multi-issue PRs (Rebase and Merge)

Amend the appropriate commit:
git add -u
git commit --amend -C HEAD
git push -f origin SAK-12345
Or use interactive rebase:
git rebase -i HEAD~3  # Adjust number as needed
git push -f origin SAK-12345
5

Comment on the PR

Notify reviewers that you’ve addressed their feedback.
Only use git push -f (force push) to your own fork, never to the main repository.

​
Code Style Guidelines

​
Java Style

List<String> names = new ArrayList<>();
Map<String, Integer> counts = new HashMap<>();
String userName = userService.getCurrentUser().getDisplayName();

​
Commit Messages

Format: <issue key> <component> <brief description> Examples: 
SAK-12345 Assignments add option x when creating an assignment
SAK-23456 Gradebook fix NPE when grade is null
SAK-34567 Forums improve accessibility for screen readers

​
JavaScript/Web Components

  • Use ES2022+ features
  • No jQuery in new code
  • Prefer modern DOM APIs
  • Use Lit components for UI
  • Keep state local and explicit
  • No global variables

​
HTML Attributes

Use kebab-case for class and id attributes: 
<!-- Correct -->
<div class="assignment-list" id="assignment-item-123">

<!-- Avoid -->
<div class="assignmentList" id="assignmentItem123">

​
Accessibility

  • Use semantic HTML elements
  • Add ARIA labels for screen readers
  • Ensure keyboard navigation
  • Test with accessibility tools
  • Include alt text for images

​
Testing Requirements

  • Include unit tests for new code
  • Update existing tests for changes
  • Add Playwright E2E tests for UI flow changes
  • All tests must pass before merge

​
Security Issues

Security issues are handled differently:
1

Request security access

Email the contact on the Security Policy page to get access to:
  • Security mailing list
  • Security JIRA work group
2

Create security JIRA

Create a JIRA ticket with “security issue” indicated (dropdown option).
3

Submit fix

Either:
  • Request access to private sakai-security repo and submit PR there
  • Attach a diff to the JIRA ticket
4

Review process

PRs and issues are reviewed at Security WG or Core Team meetings before releases.
For high-priority security issues, email the security list directly.

​
Communication Channels

​
Mailing Lists

Join the Sakai developer mailing list: 
# Subscribe
Send email to: [email protected]

​
Slack

Join the Apereo Slack workspace:
  1. Sign up at apereo.slack.com/signup
  2. If your institution isn’t listed, email [email protected] or [email protected]

​
Wiki and Confluence

Development documentation:

​
Release Process

Sakai follows a regular release schedule:

​
Current Versions

  • Sakai 25.2: Current development (Q2 2026)
  • Sakai 23.5: Maintenance release (Q4 2025)
  • Sakai 22.6: Maintenance release (Q4 2025)

​
Version Support

Community-supported versions receive:
  • Bug fixes
  • Security updates
  • Feature enhancements
Legacy versions receive:
  • Security updates only

​
Best Practices

Small PRs

Keep pull requests focused and small for faster review.

Test Thoroughly

Test your changes in multiple browsers and scenarios.

Document Changes

Update documentation when adding features.

Ask Questions

Use mailing lists and Slack when you need help.

​
Next Steps

Setup Guide

Set up your development environment

Building Sakai

Learn build commands and deployment

Tool Development

Start developing Sakai tools

Testing Guide

Write comprehensive tests

Build docs developers (and LLMs) love

Get started for freeTalk to us