# 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. Contributing code](#contributing-code) - [3.1. Coding style](#coding-style) - [3.1.1. Language](#language) - [3.1.2. Code Formatting](#code-formatting) - [3.1.3. Additional Style Rules](#additional-style-rules) - [3.2. Submitting patches / Pull Requests](#submitting-patches--pull-requests) - [3.2.1. Commit messages](#commit-messages) - [3.2.2. Commit messages for patches authored by someone else](#commit-messages-for-patches-authored-by-someone-else) - [4. Tools](#tools) - [4.1. Using clang-format](#using-clang-format) - [4.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/dosbox-staging/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][clanga], [Coverity][coverity], [PVS][pvs], [LGTM]. - Look at our groomed list of features we want implemented in the [Backlog](https://github.com/dosbox-staging/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/dosbox-staging/dosbox-staging/projects) and pick one of tasks in "To do" column. - Peruse through the list of [open bug reports](https://github.com/dosbox-staging/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. [coverity]: https://scan.coverity.com/projects/dosbox-staging/ [lgtm]: https://lgtm.com/projects/g/dosbox-staging/dosbox-staging/ [clanga]: https://github.com/dosbox-staging/dosbox-staging/actions?query=workflow%3A%22Code+analysis%22 [pvs]: https://github.com/dosbox-staging/dosbox-staging/actions?query=workflow%3A%22PVS-Studio+analysis%22 # 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 the main branch. Do not do mass reformatting or renaming of existing code. ### Language We use C-like C++17. 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++17 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 and range-expression loops, std::array instead of fixed C-arrays, 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 occasionally 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 " $ 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: ``` 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/main/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 :py3f ~/.vim/clang-format.py imap :py3f ~/.vim/clang-format.py 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.