128 lines
4.9 KiB
Markdown
128 lines
4.9 KiB
Markdown
# Contributing
|
|
|
|
Contributions to Astaroth are very welcome!
|
|
|
|
This document details how to create good contributions. There are two primary concerns:
|
|
|
|
1. The codebase should stay maintainable and commits should adhere to a consistent style.
|
|
2. New additions should not disrupt the work of others.
|
|
|
|
## Basic workflow
|
|
|
|
> "There is something that needs fixing"
|
|
|
|
1. Create your work. See [Programming](#markdown-header-programming) and [Committing](#markdown-header-committing) .
|
|
2. When done, check that autotests still pass by running `./ac_run -t`.
|
|
3. **[Recommended]:** Autoformat your code. See [Formatting](#markdown-header-formatting).
|
|
4. Create a pull request.
|
|
|
|
## Programming
|
|
* **Strive for code clarity over micro-optimizations.**
|
|
* Readability and simplicity should always be preferred over anything else outside of performance-critical parts.
|
|
* Give variables meaningful names and add comments to parts that are not immediately clear from context.
|
|
* **Avoid breaking existing functionality.**
|
|
* Do not modify existing interface functions in any way. Bugfixes are exceptions. If you need new functionality, create a new function.
|
|
* Do not rename or redefine global variables or constants.
|
|
|
|
## Committing
|
|
* Prefer multiple small commits over few large ones.
|
|
* Provide meaningful commit messages.
|
|
* If a feature consists of multiple commits, consider creating a new branch. See [Managing feature branches](#markdown-header-managing-feature-branches) and [About branches in general](#markdown-header-about-branches-in-general) for more details. When done, issue the pull request to the new branch.
|
|
|
|
## Formatting
|
|
|
|
If you have `clang-format`, you may run `scripts/fix_style.sh`. This script will recursively fix style of all the source files down from the current working directory. The script will ask for a confirmation before making any changes.
|
|
|
|
> **WARNING** The script will replace old source files with new formatted versions. Ensure that you have committed your changes before running `fix_style.sh` to be safe.
|
|
|
|
Basic rules:
|
|
|
|
- Use [K&R indentation style](https://en.wikipedia.org/wiki/Indentation_style#K&R_style) and 4 space tabs.
|
|
- Line width is 100 characters.
|
|
- Start function names after a linebreak in source files.
|
|
- [Be generous with `const` type qualifiers](https://isocpp.org/wiki/faq/const-correctness).
|
|
- When in doubt, see [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html).
|
|
|
|
## Header example:
|
|
```cpp
|
|
// Licence notice and doxygen description here
|
|
#pragma once
|
|
#include "avoid_including_headers_here.h"
|
|
|
|
/** Doxygen comments */
|
|
void globalFunction(void);
|
|
```
|
|
|
|
|
|
## Source example:
|
|
```cpp
|
|
#include "parent_header.h"
|
|
|
|
#include <standard_library_headers.h>
|
|
|
|
#include "other_headers.h"
|
|
#include "more_headers.h"
|
|
|
|
typedef struct {
|
|
int data;
|
|
} SomeStruct;
|
|
|
|
static inline int small_function(const SomeStruct& stuff) { return stuff.data; }
|
|
|
|
// Pass constant structs always by reference (&) and use const type qualifier.
|
|
// Modified structs are always passed as pointers (*), never as references.
|
|
// Constant parameters should be on the left-hand side, while non-consts go to the right.
|
|
static void
|
|
local_function(const SomeStruct& constant_struct, SomeStruct* modified_struct)
|
|
{
|
|
modified_struct->data = constant_struct.data;
|
|
}
|
|
|
|
void
|
|
globalFunction(void)
|
|
{
|
|
return;
|
|
}
|
|
```
|
|
|
|
## Managing feature branches
|
|
|
|
1. Ensure that you're on the latest version of master. `git checkout master && git pull`
|
|
|
|
2. Create a feature branch with `git checkout -b <feature_name_year-month-date>`, f.ex. `git checkout -b forcingtests_2019-01-01`
|
|
|
|
3. Do your commits in that branch until your new feature works
|
|
|
|
4. Merge master with your feature branch `git merge master`
|
|
|
|
5. Resolve the conflicts and test that the code compiles and still works by running `./ac_run -t`
|
|
|
|
6. If everything is OK, commit your final changes to the feature branch and merge it to master `git commit && git checkout master && git merge <your feature branch> && git push`
|
|
|
|
7. Unless you really have to keep your feature branch around for historical/other reasons, remove it from remote by calling `git push origin --delete <your feature branch>`
|
|
|
|
A flowchart is available at [doc/commitflowchart.png](https://bitbucket.org/jpekkila/astaroth/src/2d91df19dcb3/doc/commitflowchart.png?at=master).
|
|
|
|
## About branches in general
|
|
|
|
* Unused branches should not kept around after merging them into master in order to avoid cluttering the repository.
|
|
|
|
* `git branch -a --merged` shows a list of branches that have been merged to master and are likely not needed any more.
|
|
|
|
* `git push origin --delete <feature branch>` deletes a remote branch while `git branch -d <feature branch>` deletes a local branch
|
|
|
|
* If you think that you have messed up and lost work, run `git reflog` which lists the latests commits. All work that has been committed should be accessible with the hashes listed by this command with `git checkout <reflog hash>`.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|