|
| 1 | +# Contributing to SDL |
| 2 | + |
| 3 | +We appreciate your interest in contributing to SDL, this document will describe how to report bugs, contribute code or ideas or edit documentation. |
| 4 | + |
| 5 | +**Table Of Contents** |
| 6 | + |
| 7 | +- [Filing a GitHub issue](#filing-a-github-issue) |
| 8 | + - [Reporting a bug](#reporting-a-bug) |
| 9 | + - [Suggesting enhancements](#suggesting-enhancements) |
| 10 | +- [Contributing code](#contributing-code) |
| 11 | + - [Forking the project](#forking-the-project) |
| 12 | + - [Following the style guide](#following-the-style-guide) |
| 13 | + - [Running the tests](#running-the-tests) |
| 14 | + - [Opening a pull request](#opening-a-pull-request) |
| 15 | +- [Contributing to the documentation](#contributing-to-the-documentation) |
| 16 | + - [Editing a function documentation](#editing-a-function-documentation) |
| 17 | + - [Editing the wiki](#editing-the-wiki) |
| 18 | + |
| 19 | +## Filing a GitHub issue |
| 20 | + |
| 21 | +### Reporting a bug |
| 22 | + |
| 23 | +If you think you have found a bug and would like to report it, here are the steps you should take: |
| 24 | + |
| 25 | +- Before opening a new issue, ensure your bug has not already been reported on the [GitHub Issues page](https://github.com/libsdl-org/SDL/issues). |
| 26 | +- On the issue tracker, click on [New Issue](https://github.com/libsdl-org/SDL/issues/new). |
| 27 | +- Include details about your environment, such as your Operating System and SDL version. |
| 28 | +- If possible, provide a small example that reproduces your bug. |
| 29 | + |
| 30 | +### Suggesting enhancements |
| 31 | + |
| 32 | +If you want to suggest changes for the project, here are the steps you should take: |
| 33 | + |
| 34 | +- Check if the suggestion has already been made on: |
| 35 | + - the [issue tracker](https://github.com/libsdl-org/SDL/issues); |
| 36 | + - the [discourse forum](https://discourse.libsdl.org/); |
| 37 | + - or if a [pull request](https://github.com/libsdl-org/SDL/pulls) already exists. |
| 38 | +- On the issue tracker, click on [New Issue](https://github.com/libsdl-org/SDL/issues/new). |
| 39 | +- Describe what change you would like to happen. |
| 40 | + |
| 41 | +## Contributing code |
| 42 | + |
| 43 | +This section will cover how the process of forking the project, making a change and opening a pull request. |
| 44 | + |
| 45 | +### Forking the project |
| 46 | + |
| 47 | +The first step consists in making a fork of the project, this is only necessary for the first contribution. |
| 48 | + |
| 49 | +Head over to https://github.com/libsdl-org/SDL and click on the `Fork` button in the top right corner of your screen, you may leave the fields unchanged and click `Create Fork`. |
| 50 | + |
| 51 | +You will be redirected to your fork of the repository, click the green `Code` button and copy the git clone link. |
| 52 | + |
| 53 | +If you had already forked the repository, you may update it from the web page using the `Fetch upstream` button. |
| 54 | + |
| 55 | +### Following the style guide |
| 56 | + |
| 57 | +Code formatting is done using a custom `.clang-format` file, you can learn more about how to run it [here](https://clang.llvm.org/docs/ClangFormat.html). |
| 58 | + |
| 59 | +Some legacy code may not be formatted, as such avoid formatting the whole file at once and only format around your changes. |
| 60 | + |
| 61 | +For your commit message to be properly displayed on GitHub, it should contain: |
| 62 | + |
| 63 | +- A short description of the commit of 50 characters or less on the first line. |
| 64 | +- If necessary, add a blank line followed by a long description, each line should be 72 characters or less. |
| 65 | + |
| 66 | +For example: |
| 67 | + |
| 68 | +``` |
| 69 | +Fix crash in SDL_FooBar. |
| 70 | +
|
| 71 | +This addresses the issue #123456 by making sure Foo was successful |
| 72 | +before calling Bar. |
| 73 | +``` |
| 74 | + |
| 75 | +### Running the tests |
| 76 | + |
| 77 | +Tests allow you to verify if your changes did not break any behaviour, here are the steps to follow: |
| 78 | + |
| 79 | +- Before pushing, run the `testautomation` suite on your machine, there should be no more failing tests after your change than before. |
| 80 | +- After pushing to your fork, Continuous Integration (GitHub Actions) will ensure compilation and tests still pass on other systems. |
| 81 | + |
| 82 | +### Opening a pull request |
| 83 | + |
| 84 | +- Head over to your fork's GitHub page. |
| 85 | +- Click on the `Contribute` button and `Open Pull Request`. |
| 86 | +- Fill out the pull request template. |
| 87 | +- If any changes are requested, you can add new commits to your fork and they will be automatically added to the pull request. |
| 88 | + |
| 89 | +## Contributing to the documentation |
| 90 | + |
| 91 | +### Editing a function documentation |
| 92 | + |
| 93 | +The wiki documentation for API functions is synchronised from the headers' doxygen comments. As such, all modifications to syntax; function parameters; return value; version; related functions should be done in the header directly. |
| 94 | + |
| 95 | +### Editing the wiki |
| 96 | + |
| 97 | +Other changes to the wiki should done directly from https://wiki.libsdl.org/ |
0 commit comments