243 lines
10 KiB
Markdown
243 lines
10 KiB
Markdown
# Contributing to dosbox-staging
|
|
|
|
Thank you for your interest in contributing to dosbox-staging! There are many
|
|
ways to participate, and we appreciate all of them. This document is a bit long,
|
|
so here are links to the major sections:
|
|
|
|
- [1. Feature requests and bug reports](#feature-requests-and-bug-reports)
|
|
- [2. Find something to work on](#find-something-to-work-on)
|
|
- [3. Build dosbox-staging](#build-dosbox-staging)
|
|
- [4. Contributing code](#contributing-code)
|
|
- [4.1. Coding style](#coding-style)
|
|
- [4.1.1. Language](#language)
|
|
- [4.1.2. Code Formatting](#code-formatting)
|
|
- [4.1.3. Additional Style Rules](#additional-style-rules)
|
|
- [4.2. Submitting patches / Pull Requests](#submitting-patches--pull-requests)
|
|
- [4.2.1. Commit messages](#commit-messages)
|
|
- [4.2.2. Commit messages for patches authored by someone else](#commit-messages-for-patches-authored-by-someone-else)
|
|
- [5. Tools](#tools)
|
|
- [5.1. Using clang-format](#using-clang-format)
|
|
- [5.2. Summarize warnings](#summarize-warnings)
|
|
|
|
# Feature requests and bug reports
|
|
|
|
If you find a [feature request][enhancement_label], you're interested in,
|
|
leave a comment, or an emote - it will help us to decide where to focus our
|
|
development effort.
|
|
|
|
Report bugs via our [bugtracker][issues]. Issues and requests reported
|
|
via comments on social media or private messages are very likely going to be
|
|
lost.
|
|
|
|
[enhancement_label]: https://github.com/dosbox-staging/dosbox-staging/issues?q=is%3Aissue+is%3Aopen+label%3Aenhancement
|
|
[issues]: https://github.com/dosbox-staging/dosbox-staging/issues
|
|
|
|
# Find something to work on
|
|
|
|
There's plenty of tasks to work on all around, here are some ideas:
|
|
|
|
- Test with your DOS games.
|
|
- Package dosbox-staging for your OS.
|
|
- Improve documentation (in the repo, or in the
|
|
[project wiki](https://github.com/dreamer/dosbox-staging/wiki)).
|
|
- Promote the project in gaming communities :)
|
|
- Provide translations (!)
|
|
- Look at warning in code (build with `-Wall -Weffc++` to see the long list
|
|
of potential code improvements), and try to eliminate them.
|
|
- Look through our static analysis reports, pick an issue, investigate if the
|
|
problem is true-positive or false-positive and if the code can be improved.
|
|
See artifacts/reports in: [Clang][code-analysis], [Coverity][coverity],
|
|
[PVS][pvs]
|
|
- Look at our groomed list of features we want implemented in the
|
|
[Backlog](https://github.com/dreamer/dosbox-staging/projects/3) - if the issue
|
|
is not assigned to anyone, then it's for the pickings! Leave a comment saying
|
|
that you're working on it.
|
|
- Find next release project in our
|
|
[projects list ](https://github.com/dreamer/dosbox-staging/projects)
|
|
and pick one of tasks in "To do" column.
|
|
- Peruse through the list of
|
|
[open bug reports](https://github.com/dreamer/dosbox-staging/issues?q=is%3Aissue+is%3Aopen+label%3Abug)
|
|
and try to reproduce or fix them.
|
|
|
|
Or just send us a Pull Request with your improvement
|
|
(read: ["Submitting patches"](#submitting-patches-pull-requests)).
|
|
|
|
If you plan to work on a new, bigger feature - then it might be good idea to
|
|
discuss it with us early, e.g. by creating a new bugtracker issue.
|
|
|
|
[pvs]: https://github.com/dosbox-staging/dosbox-staging/actions?query=workflow%3A%22PVS-Studio+analysis%22
|
|
[code-analysis]: https://github.com/dosbox-staging/dosbox-staging/actions?query=workflow%3A%22Code+analysis%22
|
|
[coverity]: https://scan.coverity.com/projects/dosbox-staging
|
|
|
|
# Build dosbox-staging
|
|
|
|
Basic build instructions are in [README.md][readme-b]; take a moment to read
|
|
[INSTALL][install] file as well. These are good enough to get you started :)
|
|
|
|
Detailed build instructions are in [BUILD.md][build-doc] file.
|
|
|
|
[readme-b]: https://github.com/dosbox-staging/dosbox-staging#build-instructions
|
|
[install]: https://github.com/dosbox-staging/dosbox-staging/blob/master/INSTALL
|
|
[build-doc]: https://github.com/dosbox-staging/dosbox-staging/blob/master/BUILD.md
|
|
|
|
# Contributing code
|
|
|
|
## Coding style
|
|
|
|
These rules apply to code in `src/` and `include/` directories.
|
|
They do not apply to code in `src/libs/` directory (libraries in there
|
|
have their own coding conventions).
|
|
|
|
Rules outlined below apply to new code landing in master branch.
|
|
Do not do mass reformating or renaming of existing code.
|
|
|
|
### Language
|
|
|
|
We use C-like C++14. To clarify:
|
|
|
|
- Avoid designing your code in complex object-oriented style.
|
|
This does not mean "don't use classes", it means "don't use stuff like
|
|
multiple inheritance, overblown class hierarchies, operator overloading,
|
|
iostreams for stdout/stderr, etc, etc".
|
|
- C++14 has rich STL library, use it (responsibly - sometimes using
|
|
C standard library makes more sense).
|
|
- Use modern C++ features like `constexpr`, `static_assert`, managed pointers,
|
|
lambda expressions, for-each loops, etc.
|
|
- Avoid using exceptions. C++ exceptions are trickier than you think.
|
|
No, you won't get it right. Or person touching the code after you won't get
|
|
it right. Or person using your exception-ridden interface won't get it right.
|
|
Let errors like `std::logic_error` or `std::bad_alloc` terminate the
|
|
process, so it's easier to notice during testing and can be fixed early.
|
|
- Avoid complex template metaprogramming. Simple templates are fine.
|
|
- Avoid complex macros. If possible, write a `constexpr` function or simple
|
|
template instead.
|
|
- Never write `using namespace std;`. We don't want any confusion about what
|
|
comes from STL and what's project-specific.
|
|
- Before using some platform-specific API - check if SDL2 provides
|
|
cross-platform interface for it. It probably does.
|
|
|
|
### Code Formatting
|
|
|
|
For new code follow K&R style - see [Linux coding style] for examples and some
|
|
advice on good C coding style.
|
|
|
|
Following all the details of formatting style is tedious, that's why we use
|
|
custom clang-format ruleset to make it crystal clear, skip to
|
|
["Using clang-format"](#using-clang-format) section to learn how.
|
|
|
|
[Linux coding style]:https://www.kernel.org/doc/html/latest/process/coding-style.html
|
|
|
|
### Additional Style Rules
|
|
|
|
1. Sort includes according to: [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html#Names_and_Order_of_Includes)
|
|
2. NEVER use Hungarian notation.
|
|
3. Most old code uses naming convention `MODULENAME_FunctionName` for public
|
|
module interfaces. Do NOT replace it with namespaces.
|
|
4. Utility function names and helper functions (generic functionalities, not
|
|
tied to any specific emulation area, such as functions in
|
|
`include/support.h`) do not need to follow this convention.
|
|
Using `snake_case` names for such functions is recommended.
|
|
5. Do NOT use that convention for static functions (single file scope), class
|
|
names, methods, enums, or other constructs.
|
|
6. Class names and method names can use `CamelCase` or `snake_case`.
|
|
Be consistent, DON'T mix styles like this: `get_DefaultValue_Str` (bleh).
|
|
7. Using `snake_case` for variable names, parameter names, struct fields, and
|
|
class fields is recommended.
|
|
8. Use header guards in format: `DOSBOX_HEADERNAME_H` or
|
|
`DOSBOX_MODULENAME_HEADERNAME_H`.
|
|
|
|
## Submitting Patches / Pull Requests
|
|
|
|
Submissions via GitHub PRs are recommended. If you can't use GitHub for
|
|
whatever reason, then submitting patches (generated with `git-format-patch`)
|
|
via email is also possible - contact maintainer about the details.
|
|
|
|
Code submitted as raw source files (not patches), files attached to issue
|
|
comments, forum posts, diffs in non-git format, etc will be promptly ignored.
|
|
|
|
### Commit messages
|
|
|
|
Read [How to Write a Git Commit Message]. Then read it again, and follow
|
|
"the seven rules" :)
|
|
|
|
The only exception to these rules are commits landing from our upstream project,
|
|
so occassionally you might find a commit originating from `svn/trunk` branch,
|
|
that does not follow them. There are no other exceptions.
|
|
|
|
[How to Write a Git Commit Message]:https://chris.beams.io/posts/git-commit/
|
|
|
|
### Commit messages for patches authored by someone else
|
|
|
|
- If possible, preserve code formatting used by original author
|
|
- Record the correct author name, date when original author wrote the patch
|
|
(if known), and sign it, e.g:
|
|
|
|
```
|
|
$ git commit --amend --author="Original Author <mail-or-identifier>"
|
|
$ git commit --amend --date="15-05-2003 11:45"
|
|
$ git commit --amend --signoff
|
|
```
|
|
|
|
- Record the source of the patch so future programmers can find the context
|
|
and discussion surrounding it. Use following trailer:
|
|
|
|
```
|
|
Imported-from: <url-or-specific-identifier>
|
|
```
|
|
|
|
For an example of commit, that followed all of these rules, see:
|
|
|
|
$ git log -1 ffe3c5ab7fb5e28bae78f07ea987904f391a7cf8
|
|
|
|
# Tools
|
|
|
|
## Using clang-format
|
|
|
|
It's usually distributed with the Clang compiler, and can be integrated with
|
|
[many programming environments](https://releases.llvm.org/10.0.0/tools/clang/docs/ClangFormat.html).
|
|
|
|
Outside of your editor, code can be formatted by invoking the tool directly:
|
|
|
|
$ clang-format -i file.cpp
|
|
|
|
But it's better not to re-format the whole file at once - you can target
|
|
specific line ranges (run `clang-format --help` to learn how), or use our
|
|
helper script to format C/C++ code touched by your latest commit:
|
|
|
|
$ git commit -m "Edit some C++ code"
|
|
$ ./scripts/format-commit.sh
|
|
|
|
Run `./scripts/format-commit.sh --help` to learn about available options.
|
|
|
|
|
|
|
|
### Vim integration
|
|
|
|
Download `clang-format.py` file somewhere, and make it executable:
|
|
|
|
$ curl "https://raw.githubusercontent.com/llvm/llvm-project/master/clang/tools/clang-format/clang-format.py" > ~/.vim/clang-format.py
|
|
$ chmod +x ~/.vim/clang-format.py
|
|
|
|
Then add following lines to your `.vimrc` file:
|
|
|
|
" Integrate clang-format tool
|
|
map <C-K> :py3f ~/.vim/clang-format.py<cr>
|
|
imap <C-K> <c-o>:py3f ~/.vim/clang-format.py<cr>
|
|
|
|
Read documentation inside `clang-format.py` file in case your OS is missing
|
|
python3 support.
|
|
|
|
### MSVC integration
|
|
|
|
[ClangFormat extension on VisualStudio Marketplace](https://marketplace.visualstudio.com/items?itemName=LLVMExtensions.ClangFormat)
|
|
|
|
## Summarize warnings
|
|
|
|
Out gating mechanism tracks the number of warnings per OS/compiler.
|
|
To see a summary of warnings in your build, do a clean build and then
|
|
use script `./scripts/count-warnings.py`:
|
|
|
|
make -j "$(nproc)" |& tee build.log
|
|
./scripts/count-warnings.py build.log
|
|
|
|
Run `./scripts/count-warnings.py --help` to learn about available options.
|