Contributing to the SunPeek Project#

Thank you for thinking about investing your time in contributing to our project!

This guide provides an overview of the contribution workflow: opening an issue, creating a Merge Request (MR), reviewing, and merging — depending on how you want to contribute.

Read our Code of Conduct to keep our community safe, approachable and inclusive.

License - IMPORTANT READ THIS FIRST

By submitting contributions to SunPeek, you are agreeing to release those contributions under the same license as that applied to the repository you are submitting to. You are also agreeing to the other statements contained in the Developer Certificate of Origin. To explicitly signal acknowledgment of this, we require all commits to carry the Signed-off-by trailer, which will be interpreted as explicit agreement to the terms in the DCO. The email address used for this should match an email address associated with your GitLab account. You can add this trailer by using the -s flag with the git commit command, most git GUI clients include a configuration option to do this as well. NOTE: even in the absence of the Signed-off-by trailer, by submitting work for inclusion in the project, you acknowledge and agree to the terms in the DCO.

Did you find a bug?#

Security Vulnerability?

If you discovered a security vulnerability in SunPeek, please follow these steps:

  • Contact support@sunpeek.org directly.

  • Provide a short description.

  • Do not create a public issue.

We will get in touch with you as soon as possible.

If you’re comfortable using GitLab:

  • Ensure the bug was not already reported by searching on GitLab under Issues.

  • If you’re unable to find an open issue addressing the problem, please open a new issue in the respective repository (Backend | Frontend), using the relevant bug report templates (simply select the most appropriate template from the dropdown). Be sure to include:

    • a title and clear description,

    • as much relevant information as possible,

    • a description of the unexpected behavior and what you expected to happen instead,

    • a code sample or anonymized configuration sample demonstrating the issue.

Note

Not comfortable with GitLab? You can also report bugs via email to support@sunpeek.org or use the “Report this issue” button in the WebUI. See Troubleshooting for details.

Did you write a patch that fixes a bug?#

  • Open a new GitLab merge request with the patch. Please see Workflow for making changes for a description of the workflow for this.

  • Ensure the MR description clearly describes the problem and solution. Include the relevant issue number if applicable.

Do you intend to add a new feature or change an existing one?#

  • Check if your change has been suggested already, by searching under Issues.

  • If it has not already been proposed, suggest your change in a new issue in the respective repository (Backend | Frontend). Please use appropriate labels to allow us to triage suggestions.

  • Once your proposal has been discussed and agreed upon, create a fork of the repository, commit your changes to it, and open a Merge Request following the procedure in Workflow for making changes.

New contributor resources#

To get an overview of the project, read the Overview in the Docs. Here are some resources to help you get started with open source contributions:

Workflow for making changes#

  1. Fork the repository, and optionally clone the fork to your local machine.

  2. Follow the instructions in the respective readmes of the projects for setting up the development environment.

  3. Create a working branch in your fork and start with your changes!

  4. Write tests (if available at the project - please check the respective readme)

  5. Run the full test suites (if available at the project - please check the respective readme).

Commit your updates#

Commit changes as you work. Please use short but descriptive commit messages and commit related changes together; this will help with the review process.

Merge Request#

When you’re finished with the changes, create a merge request, also known as an MR (if you are used to GitHub, these are the same as PRs there).

  • Fill the “Ready for review” template so that we can review your MR. This template helps reviewers understand your changes as well as the purpose of your merge request.

  • Don’t forget to include a reference to the issue like closes #556 (if the MR fully addresses the issue) or initial work on #556

  • You can open an MR before you are completely ready for the changes to be merged, but please make sure that you hit the Mark Ready button when the work is finished.

  • After you open the MR, and when you add changes to it, automated tests will run

  • Please make sure that your merge request can be merged, with no conflicts, before marking it ready. This may require you to first update your fork from the upstream project and merge the main branch back into your working branch.

Once you submit your MR and mark it ready, a Maintainer will review it. If it is accepted, the MR will be merged.

  • We may ask for changes to be made before a MR can be merged, either using suggested changes or pull request comments. You can apply suggested changes directly through the UI. You can make any other changes in your fork, then commit them to your branch.

  • As you update your MR and apply changes, mark each conversation as resolved.

  • If you run into any merge issues, check out this git tutorial to help you resolve merge conflicts and other issues.

Tests#

(Note: this applies only if the respective project uses tests)

The easiest way to make sure code works is to have unit tests that our CI pipeline can run automatically. The goal is to have a test coverage after a commit that is at least as high as the last time the test was run.

For example, the backend has its tests in the /tests directory. To run tests, in a terminal in the project virtual env run python -m pytest --cov-config=.coveragerc --cov=./ ./tests/