Skip to content

Latest commit

 

History

History
233 lines (172 loc) · 9.75 KB

CONTRIBUTING.md

File metadata and controls

233 lines (172 loc) · 9.75 KB
Raw

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:

Feature requests and bug reports

If you find a feature request, 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 and requests reported via comments on social media or private messages are very likely going to be lost.

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).
  • 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, Coverity, PVS, LGTM.
  • Look at our groomed list of features we want implemented in the Backlog - 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 and pick one of tasks in "To do" column.
  • Peruse through the list of open bug reports and try to reproduce or fix them.

Or just send us a Pull Request with your improvement (read: "Submitting patches").

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.

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++20. 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" section to learn how.

Additional Style Rules

  1. Sort includes according to: Google C++ Style Guide
  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.

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.

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 <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

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.