mirror of
https://gitlab.freedesktop.org/monado/monado.git
synced 2024-12-28 02:26:16 +00:00
86 lines
4 KiB
Markdown
86 lines
4 KiB
Markdown
# Contribution Guidelines
|
|
|
|
<!--
|
|
Copyright 2018-2019 Collabora, Ltd.
|
|
|
|
SPDX-License-Identifier: CC-BY-4.0
|
|
-->
|
|
|
|
There are plenty of valid reasons why someone might not be able
|
|
to follow all of the guidelines in this section, and that's OK,
|
|
especially for new contributors or those new to open source entirely.
|
|
Let us know and we'll figure out a way to help you get involved successfully.
|
|
|
|
> Important note: Unlike the guidelines here, the Code of Conduct,
|
|
> available at <https://www.freedesktop.org/wiki/CodeOfConduct/>,
|
|
> is **not** optional,
|
|
> and applies in its entirety to anyone involved in the project,
|
|
> for the safety and comfort of all.
|
|
> See the README for associated contacts.
|
|
|
|
## Pull/Merge Requests
|
|
|
|
- If you're considering starting work on a large change that you'd like to contribute,
|
|
it is recommended to first open an issue before you start,
|
|
to begin a discussion and help smooth the acceptance of your contribution.
|
|
|
|
- If you are able, please make sure to run clang-format
|
|
(ideally version 11 or newer) before each commit,
|
|
so that you only commit things that are cleanly styled.
|
|
Consistent, machine-performed formatting improves readability and makes it easier for others to contribute.
|
|
It also makes it easier to review changes.
|
|
If you can't run clang-format, mention this fact in your request and we'd be happy to help,
|
|
either in a single "Clean up formatting." commit on top of your work,
|
|
or by "re-writing history" (with your permission and leaving your commit authorship intact),
|
|
revising each commit to apply formatting.
|
|
|
|
- Android Java and Kotlin code can be formatted using "Spotless" by running `./gradlew spotlessApply`.
|
|
|
|
- Avoid including whitespace or other formatting changes to unrelated code when committing.
|
|
The `git add -p` command or the "stage selected lines/hunks" feature of various Git GUIs are
|
|
great ways of making sure you only stage and commit the changes that you mean to.
|
|
Relatedly, `git commit -v` (if you commit from the command line) can be a great help
|
|
in making sure you aren't committing things you don't mean to,
|
|
by showing the diff you're committing in your commit message editor.
|
|
(This can even be set system-wide in `git config --global commit.verbose true`
|
|
if you find it as life-changing as many others have - thanks
|
|
[emilyst](https://twitter.com/emilyst/status/1039205453010362368).)
|
|
|
|
- If you can, before submitting a pull/merge request, try building with clang-tidy enabled,
|
|
and if you touched any code that has or should have documentation,
|
|
build and check the documentation and see if it looks OK.
|
|
|
|
- We work to keep the code free of warnings -
|
|
please help by making sure your changes build cleanly (and pass all tests).
|
|
When on compilers that take warning flags like gcc and clang do,
|
|
the build system automatically turns on quite a few of them.
|
|
If you can't figure out a warning, mention it in the request so we can figure it out together.
|
|
|
|
- We use [Proclamation](https://gitlab.com/proclamation/proclamation) to generate release notes.
|
|
After creating a merge request for a substantial change, please create one or more changelog
|
|
fragments on the branch describing the changes. See
|
|
[doc/changes/README.md](doc/changes/README.md) for more info.
|
|
|
|
### Issues
|
|
|
|
Constructive issues are a valued form of contribution.
|
|
Please try to include any relevant information
|
|
(whether it is a request for improvement or a bug report).
|
|
We'll try to respond promptly,
|
|
but there is no guarantee or warranty (as noted in the license),
|
|
absent any externally-arranged consulting or support contract.
|
|
|
|
Since this is a runtime/implementation of an API used by other applications,
|
|
bug reports should include:
|
|
|
|
- details about your build environment
|
|
- architecture
|
|
- compiler
|
|
- compiler version
|
|
- build flags (defines, configuration/feature flags)
|
|
- associated application code
|
|
- for logic/execution errors, a new (failing) test case is ideal,
|
|
otherwise a description of expected and actual behavior
|
|
- if you cannot disclose your code, or even if you can,
|
|
an "artificial", minimally-sized example can be very valuable.
|