libsdl-org
Guidelines for new contributors
Hi,
I wanted to share a few ideas I came up with to make contributions for new users more accessible.
Of course, any feedback is greatly appreciated!
Defining a Coding Style/Format/Convention
While most source files have a modeline comment /* vi: set ts=4 sw=4 expandtab: */, some have an additional sts=4 parameter in it (such as SDL.c).
Modeline seems to have several drawbacks, as far as I can tell it only works in the Vi/Vim/Neovim family. Moreover, in the past couple of years, several CVE reported about how Arbitrary Code Execution could be achieved through modeline.
A suitable replacement would, in my opinion, be a .clang-format file. It would allow very flexible customization of the formatting rule and have them applied to the entire project. It is also widely supported by IDEs and text editors (Visual Studio, CLion, Emacs, Vim plugin, Visual Studio Code) and can easily be added as a git pre-commit hook. It supports C, C++ and Objective-C.
For CMake, the cmake-format tool provides similar features. Reading the configuration from a .cmake-format.(yaml|json) file placed at the top of the repository. It can easily be installed through Python's pip and integrated through pre-commit.
While one may argue this is mostly aesthetic, having well defined formatting rules would allow new users looking to contribute to quickly get started as the whole code base would be more consistent and easier to read.
Finally, the naming style can be enforced with a tool such as clang-tidy, which settings can be set globally through a .clang-tidy file. But as mentioned in #3519, this is something that may need to be saved for an SDL3 update where we can be more flexible with the function (re)naming.
Creating a CONTRIBUTING File
Github's community page reports that it is unable to find a CONTRIBUTING file. Similar to how there is a template for pull requests, this file is linked to users when they want to open a PR to ensure they follow the repository's guidelines. Typically, this file would contain:
- Steps for creating good issues or pull requests. (How to word commit messages, what to include in the issues/PR)
- Links to external documentation, mailing lists, or a code of conduct.
- What test suite to run.
Currently, the closest to it currently would be the docs/README.md file. For it to be picked up by Github, it would simply need to be renamed CONTRIBUTING.md as the docs folder is scanned for this file.
Similar to how there is a contribution guide for the wiki, this could guide newcomers to the appropriate resources and most likely making PR faster to merge.
Good ideas! Do you want to submit pull requests that implement these changes?
Defining a Coding Style/Format/Convention
Having a .editorconfig might be a good tool-neutral way to do this.
You've been making a bunch of great contributions. Would you mind writing this documentation with fresh eyes, at your leisure?
FYI, we've added a .clang-format and .editorconfig file to take care of editors that automatically format code for you.
Thank you for the follow-up, work has indeed been quite hectic lately.
I will try to work on the CONTRIBUTING file in the upcoming days.
Thank you for your comprehension!