Welcome! We'd love for you to contribute to Scenic's code and make it an even more incredible tool!
Scenic is currently being maintained by a full-time small team of developers working for the Société des Arts Technologiques (SAT), a non-profit based in Montréal, Canada for which this software was originally developed. This core team adds features and bug fixes according to the SAT's interests and needs; however, community contributions on this project are more than welcome! There are many ways to contribute, including submitting bug reports, improving documentation, adding unit tests, adding support for a new language, submitting feature requests, reviewing new submissions, or contributing code that can be incorporated into the project. We appreciate all contributions from the community!
This document describes our development process. Following these guidelines shows that you respect the time and effort of the developers managing this project. In return, you will be shown respect in addressing your issue, reviewing your changes, and incorporating your contributions.
Code of Conduct
Please create a new Gitlab issue for any major changes and enhancements that you wish to make. Please provide the feature you would like to see, why you need it, and how it will work. Discuss your ideas transparently and get developer feedback before proceeding.
Major changes that you wish to contribute to the project should be discussed first in a Gitlab issue that clearly outlines the changes and benefits of the feature.
Small changes can directly be crafted and submitted to the repository as a Merge Request. See the section about the Merge Request Process.
If you find a security vulnerability, do NOT open an issue. Email firstname.lastname@example.org instead.
Before you submit your issue, please search the issue tracker - maybe your question or issue has already been identified or addressed.
If you find a bug in the source code, you can help us by submitting an issue to our GitLab issue tracker. Even better, you can submit a Merge Request with a fix.
Of course, please include as many information as possible in your issue: branch name and version, OS version, expected and observed behavior, system information (such as graphic drivers version), log files, etc. Most importantly, provide a step-by-step procedure on how to reproduce your bug. Check out our page on issue reporting to get pointers on how to get logs and backtraces from Scenic.
You are welcome to add unit tests if you spot some code that isn't covered by the existing tests.
We do not expect you to add unit tests when doing only minor changes to the codebase. We expect, however, the tests to pass when you're finished with your work.
When adding a new feature or doing major changes to the code, we expect you to add the relevant unit tests to the code.
In any cases, please run the tests on your computer first and ensure that they pass before pushing them to the repository. The CI pipeline will spot any broken tests, but we prefer that you make the necessary verifications beforehand rather than making the CI fail pointlessly.
You can run tests with the following command:
Should you have a suggestion for the documentation, you can open an issue and outline the problem or improvement you have - however, creating the doc fix yourself is much better!
If you want to help improve the docs, it's a good idea to let others know what you're working on to minimize duplication of effort. Create a new issue (or comment on a related existing one) to let others know what you're working on. If you're making a small change (typo, phrasing) don't worry about filing an issue first.
For large fixes, please build and test the documentation before submitting the MR to be sure you haven't accidentally introduced any layout or formatting issues.
In order to rebuild and serve the documentation, run the following command:
npm run doc:build # Build the user documentation npm run doc:serve # Serve the user documentation
Scenic is currently available in both French and English, with English being the default language. Should you spot a typo or a mistake in a translated string, you can directly fix it in the code and submit a merge request without having to open an issue. If you wish to add support for another language, open a new issue and we will be more than happy to discuss it with you!
Updating Localization Files
Localization is handled by i18next. Localization files are stored in
assets/locales/<lang>/locale.json. Simply add your localized string at the end of the appropriate file.
Finding an Issue
The list of outstanding feature requests and bugs can be found on our GitLab issue tracker. Pick an unassigned issue that you think you can accomplish and add a comment that you are attempting to do it.
This project follows the git flow branching model of product development.
The master branch contains the latest stable production release, and is updated by the core developer team. Each commit in the master branch is in fact a production release and is tagged as such. The develop branch contains the latest development version of the project.
When contributing to the project, you should create a new feature branch based off the develop branch.
Always give a short but meaningful name to this new branch, and follow these conventions:
- A branch that aims to fix something (bug, documentation, tests, etc.) should be named fix/\<branchname>
- A branch that aims to add something new (feature, tests, localization, etc.) should be named feat/\<branchname>
- The branch cannot be named master, develop, release/* or hotfix/*
When your feature branch is ready, submit a Merge Request to develop. When the MR is approved and your changes merged, you can safely delete your feature branch.
Core developers will prepare new releases regularly by creating a release branch from develop (named release/
In the event that a severe bug is detected on master, a special hotfix branch will be created (named hotfix/
Code Formatting and Style Guidelines
CSS must be linted using stylelint.
Python files must respect the PEP8 Style Guide (with a maximum line length set to 120).
C++ files must respect the Google C++ Style Guide, with 2 exceptions:
- a function call’s arguments will either be all on the same line or will have one line each.
- a function declaration’s or function definition’s parameters will either all be on the same line or will have one line each.
You may find non-compliant code in the project, but newly introduced code must follow these guidelines.
The .editorconfig file present in the dev-tools repository automatically trims trailing whitespaces. However, if you ever need to, please submit whitespace cleanups in a separate merge request.
Git Commit Guidelines
Your commit message must follow these guidelines:
- The message must start with the appropriate Gitmoji, followed by a whitespace.
- It must be written using the imperative tense.
- It must be strictly no greater than 50 characters long.
- The subject must stand on its own and not make external references, such as bug numbers.
- For example:
🌐 Update localization strings
For the sake of uniformity, please write all of your commit messages in English.
For further notes about git commit messages, please read this blog post.
This repository includes a CI pipeline, used to validate that incoming commits do not break the build, and that all unit tests still pass. It will be run automatically when a new commit is pushed to the repository. If the pipeline fails, it is your responsability to checkout the CI Jobs page and figure out how to fix it. A Merge Requests that breaks the pipeline will not be merged by the core developers.
Merge Request Process
When you are ready to submit you changes for review, either for preliminary review or for consideration of merging into the project, you can create a Merge Request to add your changes into develop. Only core developers are allowed to merge your branch into develop.
Do not forget to:
- Update the relevant README.md sections, if necessary.
- Add the relevant unit tests, if needed.
- Rebase your changes in nice, clear commits if your branch's commit history is messy.
A core developer will merge your changes into develop when all feedbacks have been addressed.
The core developer team regularly checks the repository for new merge requests. We expect the CI pipeline to succeed when you submit a MR. If it doesn't, your MR will not be approved.
If the MR concerns a minor issue, it will be merged immediately after one of the core developers approves it, if the CI succeeds. For more major issues, we will wait a day or two after all feedback has been addressed before merging the request.
Once a MR has been submitted, your changes will be reviewed and constructive feedback may be provided. Feedback isn't meant as an attack, but to help make sure the highest-quality code makes it into our project. Changes will be approved once required feedback has been addressed.
By contributing to this repository, you agree that your contributions will be licensed in accordance to the LICENSE document at the root of this repository.