Skip to main content
Thank you for considering contributing to Simple Alarm Clock! This guide will help you understand how to contribute effectively.

​
About the project

Simple Alarm Clock is an open source Android alarm clock app that brings pure alarm experience by combining powerful features with a clean interface.
The application code is branched from AOSP (Android Open Source Project) and maintains compatibility with both proprietary and open source Android distributions.

​
Ways to contribute

There are many ways to contribute to Simple Alarm Clock:
1

Report bugs

Found a bug? Submit a bug report using the GitHub issue template.
2

Request features

Have an idea for a new feature? Additional feature requests are appreciated! Use the feature request template.
3

Submit code

Fix bugs, implement features, or improve documentation through pull requests.
4

Test and review

Test pull requests and provide feedback on proposed changes.
5

Improve documentation

Help improve the documentation, code comments, or examples.

​
Before you start

Before contributing code, please:
  1. Check existing issues: Search for existing issues or feature requests to avoid duplicates
  2. Set up your environment: Follow the development setup guide
  3. Understand the codebase: Familiarize yourself with the project structure and architecture
  4. Read the code of conduct: Be respectful and professional in all interactions

​
Making code contributions

​
Fork and clone

1

Fork the repository

Fork the repository on GitHub to your account.
2

Clone your fork

git clone https://github.com/YOUR_USERNAME/AlarmClock.git
cd AlarmClock
3

Add upstream remote

git remote add upstream https://github.com/yuriykulikov/AlarmClock.git

​
Create a branch

Create a new branch for your changes: 
# For a new feature
git checkout -b feature/your-feature-name

# For a bug fix
git checkout -b fix/issue-description

# For documentation
git checkout -b docs/what-you-are-documenting
Use descriptive branch names that clearly indicate what you’re working on.

​
Make your changes

When making changes:
1

Follow coding standards

The project uses:
  • Kotlin code style: Official Kotlin style
  • Formatter: ktfmt for Kotlin, Google Java Format for Java
  • Line endings: Unix (LF)
2

Write tests

Add or update tests for your changes. See the testing guide for details.
3

Format your code

Run Spotless to format your code:
./gradlew spotlessApply
4

Run tests

Ensure all tests pass:
./gradlew test
./gradlew testDevelopDebugUnitTest
5

Build the app

Verify the app builds successfully:
./gradlew assembleDevelopDebug

​
Coding standards

​
Kotlin style

The project follows the official Kotlin coding conventions:
gradle.properties
kotlin.code.style=official

​
Code formatting

All code must be formatted with Spotless: 
./gradlew spotlessApply
Formatting configuration:
  • Kotlin: ktfmt formatter with Unix line endings
  • Java: Google Java Format with Unix line endings
  • Targets: build.gradle.kts, **/*.kt, **/*.java
  • Excludes: Build directories and test resources
All pull requests must pass spotlessCheck. Format your code before committing!

​
Compiler options

The project uses specific Kotlin compiler options: 
kotlinOptions {
  freeCompilerArgs = freeCompilerArgs + 
    "-opt-in=kotlin.RequiresOptIn" + 
    "-opt-in=kotlin.Experimental"
  jvmTarget = "1.8"
}

​
Commit your changes

Write clear, descriptive commit messages: 
# Good commit messages
git commit -m "Fix alarm not ringing on Android 13+"
git commit -m "Add support for custom snooze duration"
git commit -m "Update time picker UI for better accessibility"

# Bad commit messages
git commit -m "fix bug"
git commit -m "update"
git commit -m "wip"
Commit message guidelines:
  • Use the imperative mood (“Add feature” not “Added feature”)
  • Keep the first line under 72 characters
  • Provide context in the commit body if needed
  • Reference issue numbers when applicable (e.g., “Fixes #123”)

​
Push and create a pull request

1

Push your changes

git push origin your-branch-name
2

Create pull request

Go to GitHub and create a pull request from your fork to the main repository.
3

Fill in the PR template

Provide a clear description of your changes:
  • What problem does this solve?
  • How did you test it?
  • Any breaking changes?
  • Screenshots (for UI changes)
4

Link related issues

Reference any related issues in your PR description:
Fixes #123
Related to #456

​
Pull request guidelines

​
PR requirements

Your pull request should:
  • Pass all existing tests
  • Include new tests for new functionality
  • Pass spotlessCheck (code formatting)
  • Build successfully (./gradlew assembleDevelopDebug)
  • Have a clear, descriptive title
  • Include a detailed description of changes
  • Reference related issues
  • Be based on the latest develop branch

​
PR process

  1. Automated checks: CI will automatically run tests and checks
  2. Code review: Maintainers will review your code
  3. Feedback: Address any feedback or requested changes
  4. Approval: Once approved, your PR will be merged
Be patient! Maintainers review PRs as time allows. It may take a few days to get feedback.

​
CI/CD pipeline

The project uses GitHub Actions for continuous integration. On every push and pull request, the following checks run: 
# Build the app
./gradlew assembleDevelopDebug

# Run unit tests
./gradlew testDevelopDebugUnitTest
You can see the build status on the repository: Build Status

​
Code review process

During code review, maintainers will check:
  • Code quality: Is the code clean, readable, and maintainable?
  • Tests: Are there adequate tests? Do they pass?
  • Documentation: Are changes documented?
  • Performance: Does it impact app performance?
  • Compatibility: Does it work across supported Android versions?
  • Breaking changes: Are there any breaking changes?

​
Development workflow best practices

1

Keep your fork updated

Regularly sync your fork with the upstream repository:
git fetch upstream
git checkout develop
git merge upstream/develop
2

Make small, focused PRs

Smaller PRs are easier to review and more likely to be merged quickly.
3

Test thoroughly

Test on multiple Android versions and devices if possible.
4

Respond to feedback

Be responsive to code review comments and questions.
5

Be patient and respectful

Remember that maintainers are volunteers. Be patient and respectful in all interactions.

​
Reporting bugs

When reporting bugs, please include:
  • Android version: What version of Android are you using?
  • Device: What device are you using?
  • App version: What version of Simple Alarm Clock?
  • Steps to reproduce: Clear steps to reproduce the issue
  • Expected behavior: What should happen?
  • Actual behavior: What actually happens?
  • Logs: If possible, include relevant logcat output
  • Screenshots: If applicable, add screenshots
You can also submit bug reports by sending an email to the developers.

​
Requesting features

When requesting features:
  • Check existing requests: Search for similar feature requests first
  • Describe the use case: Why is this feature needed?
  • Provide examples: How would it work? Include mockups if possible
  • Consider alternatives: Are there other ways to achieve the same goal?

​
License

By contributing to Simple Alarm Clock, you agree that your contributions will be licensed under the Apache License 2.0. 
Copyright [yyyy] [name of copyright owner]

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
The Apache 2.0 license is a permissive open source license that allows for both commercial and non-commercial use.

​
Getting help

If you need help:
  • Documentation: Check the setup guide, building guide, and testing guide
  • Issues: Search existing GitHub issues for similar problems
  • Discussions: Use GitHub Discussions for questions
  • Email: Contact the developers via email for complex questions

​
Community

Simple Alarm Clock is maintained by Yuriy Kulikov and the community.

​
Thank you!

Thank you for contributing to Simple Alarm Clock! Your contributions help make the app better for everyone.

Build docs developers (and LLMs) love

Get started for freeTalk to us