Skip to content

Commit f790fc4

Browse files
FtZPetruskaslouken
authored andcommitted
Add contributing guidelines.
1 parent 198d62d commit f790fc4

File tree

1 file changed

+97
-0
lines changed

1 file changed

+97
-0
lines changed

docs/CONTRIBUTING.md

+97
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
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

Comments
 (0)