mirror of https://github.com/Xaymar/obs-StreamFX
project: Updating contributing guidelines
This commit is contained in:
Michael Fabian 'Xaymar' Dirks
parent
671ba73088
commit
eb8d05a550
|
|
@ -1,17 +1,17 @@
|
|||
# Contributing
|
||||
This document goes over how you are expected to contribute to the project. This document is softly enforced, and considered a guideline instead of a requirement.
|
||||
This document goes over how you (and/or your organization) are expected to contribute. These guidelines are softly enforced and sometimes not required.
|
||||
|
||||
## Localization
|
||||
We use Crowdin to handle translations into many languages. Please join the [StreamFX project on Crowdin](https://crowdin.com/project/obs-stream-effects) if you are interested in improving the translations to your native tongue. Pull Requests therefore should only include changes to `en-US.ini`, and no other localization files should be touched.
|
||||
We use Crowdin to handle translations into many languages, and you can join the [StreamFX project on Crowdin](https://crowdin.com/project/obs-stream-effects) if you are interested in improving the translations to your native tongue. As Crowdin handles all other languages, Pull Requests therefore should only include changes to `en-US.ini`.
|
||||
|
||||
## Commit Guidelines
|
||||
Commits should focus on a single change, such as formatting, fixing a single bug, a single warning across the code, and similar things. This means that you should not include a fix to color format handling in a commit that implements a new encoder.
|
||||
Commits should focus on a single change such as formatting, fixing a bug, a warning across the code, and similar things. This means that you should not include a fix to color format handling in a commit that implements a new encoder, or include a fix to a bug with a fix to a warning.
|
||||
|
||||
### Linear History
|
||||
This project prefers the linear history of `git rebase`, and as such forbids merge commits. This allows all branches to be a single line back to the root, unless viewed as a whole where it becomes a tree. If you are working on a branch for a feature, bug or other thing, you should learn how to rebase back onto the main branch before making a pull request.
|
||||
This project prefers the linear history of `git rebase` and forbids merge commits. This allows all branches to be a single line back to the root, unless viewed as a whole where it becomes a tree. If you are working on a branch for a feature, bug or other thing, you should know how to rebase back onto the main branch before making a pull request.
|
||||
|
||||
### Commit Message & Title
|
||||
As the StreamFX project uses linear history without merge commits, we require a commit message format like this:
|
||||
We require a commit message format like this:
|
||||
|
||||
```
|
||||
prefix: short description
|
||||
|
|
@ -37,18 +37,16 @@ Depending on where the file is that you ended up modifying, or if you modified m
|
|||
- `/ui` -> `ui` (if not part of a `code` change)
|
||||
- Most other files -> `project`
|
||||
|
||||
Multiple prefixes should be separated by `, ` and sorted alphabetically so that a change to `ui` and `code` results in a prefix of `code, ui`. If only a single code file was changed or multiple related file with a common parent were changed, the `code` prefix should be replaced by the path to the file like in these examples:
|
||||
If multiple locations match, they should be alphabetically sorted and separated by `, `. A change to both `ui` and `code` will as such result in a prefix of `code, ui`. If a `code` change only affects a single file, or multiple files with a common parent file, the prefix should be the path of the file, like shown in the following examples:
|
||||
|
||||
- `/source/encoders/encoder-ffmpeg` -> `encoder/ffmpeg`
|
||||
- `/source/filters/filter-shader` -> `filter/shader`
|
||||
- and so on.
|
||||
|
||||
These guidelines are soft requirements and may be extended in the future.
|
||||
- `/source/encoders/handlers/handler`, `/source/encoders/encoder-ffmpeg` -> `encoder/ffmpeg`
|
||||
|
||||
## Coding Guidelines
|
||||
|
||||
### Documentation & Comments
|
||||
Your code should contain the comments where they would save time, as well as documentation for "public" facing functionality. This means that you shouldn't explain things like `1 + 1`, but should provide explanations for complex things. Consider the following:
|
||||
### Documentation
|
||||
Documentation should be present in areas where it would save time to new developers, and in areas where an API is defined. This means that you should not provide documentation for things like `1 + 1`, but for things like the following:
|
||||
|
||||
```c++
|
||||
int32_t idepth = static_cast<int32_t>(depth);
|
||||
|
|
@ -57,10 +55,16 @@ int32_t grid_size = static_cast<int32_t>(pow(2l, (idepth / 2)));
|
|||
int32_t container_size = static_cast<int32_t>(pow(2l, (idepth + (idepth / 2))));
|
||||
```
|
||||
|
||||
This would be much easier to read if it had a an explaination and didn't require parsing the math. Comments are all about saving time to developers not already invested into the code.
|
||||
```c++
|
||||
class magic_class {
|
||||
void do_magic_thing(float magic_number);
|
||||
}
|
||||
```
|
||||
|
||||
Both of these examples would be much easier to understand if they had proper documentation, and save hours if not even days of delving into code. Documentation is about saving time to new developers, and can't be replaced by code. Code is not Documentation!
|
||||
|
||||
### Naming & Casing
|
||||
Names for anything should describe the purpose or function of the thing, unless the thing is temporary such as iterators.
|
||||
All long-term objects should have a descriptive name, which can be used by other developers to know what it is for. Temporary objects should also have some information, but do not necessarily follow the same rules.
|
||||
|
||||
#### Macros
|
||||
- Casing: ELEPHANT_CASE
|
||||
|
|
@ -162,8 +166,8 @@ function example() {
|
|||
- Casing: snake_case
|
||||
- Separator: `_`
|
||||
- Prefixes:
|
||||
- `_` for private, protected
|
||||
- None for public (prefer set-/get-ters)
|
||||
- private: `_`
|
||||
- protected, public: None
|
||||
- Suffixes: None
|
||||
|
||||
##### Methods
|
||||
|
|
@ -181,6 +185,13 @@ class example {
|
|||
int example_int(); // ❌, has `_int` suffix.
|
||||
void example(); // ✔
|
||||
void example(int& result); // ✔
|
||||
|
||||
public:
|
||||
float exa_mple; // ✔
|
||||
|
||||
int example_int(); // ❌, has `_int` suffix.
|
||||
void example(); // ✔
|
||||
void example(int& result); // ✔
|
||||
}
|
||||
|
||||
struct example {
|
||||
|
|
@ -228,9 +239,14 @@ Interface Classes are handled like normal classes. There are no prefixes or suff
|
|||
### Preprocessor Macros
|
||||
Pre-processor Macros are a "last stand" option, when all other options fail or would produce worse results. If possible and cleaner to do so, prefer the use of `constexpr` code.
|
||||
|
||||
### Global Variables
|
||||
Only allowed if there is no other cleaner way to handle this.
|
||||
|
||||
### Classes
|
||||
Special rules for `class`
|
||||
|
||||
#### Members
|
||||
Members of classes should be private and only accessible via get/set methods.
|
||||
All class members must be `private` and only accessible through get-/setters. The setter of a member should also validate if the setting is within an allowed range, and throw exceptions if an error occurs. If there is no better option, it is allowed to delay validation until a common function is called.
|
||||
|
||||
## Building
|
||||
Please read [the guide on the wiki](https://github.com/Xaymar/obs-StreamFX/wiki/Building) for building the project.
|
||||
|
|
|
|||
Loading…
Reference in New Issue