diff options
| -rw-r--r-- | CONTRIBUTIONS.md | 186 |
1 files changed, 150 insertions, 36 deletions
diff --git a/CONTRIBUTIONS.md b/CONTRIBUTIONS.md index 5132eab..9b4aa1e 100644 --- a/CONTRIBUTIONS.md +++ b/CONTRIBUTIONS.md @@ -1,21 +1,26 @@ # Contributing to sxwm -Firstly, thanks for taking the time to contribute to sxwm! I appreciate your interest in improving the project. +Firstly, thanks for taking the time to contribute to `sxwm`! Your interest +in improving the project is truly appreciated. ## Code Style and Formatting -There is an included clangd formatting file with this inside, but it wont do everything for you. +There is an included `clangd` formatting file, but it won’t do everything for you. +Please follow the rules below to keep the codebase consistent and clean. ### Indentation -Indentation must always be **tabs** not spaces. + +* Use **tabs** for indentation — never spaces. ### Blocks -- All blocks of C code must be encased with curly braces `{}` -- Blocks must also be seperated, each statement on a new line -- Statements must be formatted with a space between the keyword and the brackets + +* All blocks of C code must be wrapped in curly braces `{}`. +* Each statement must be on its own line. +* Always add a space between keywords and the opening parenthesis. **Example**: -``` c + +```c if (x) { y(); } @@ -25,12 +30,25 @@ else { ``` ### Comments -Comments must be like this to keep the look consistent across the whole program. -`/* this is a comment */` + +* Use this format for comments to maintain consistency: + +```c +/* this is a comment */ +``` + +* For temporary notes, use: + +```c +/* TODO: something to fix */ +/* FIXME: known issue */ +``` ### Function Declarations -They must look like this -``` c + +Functions should look like this: + +```c void function_x(void) { } @@ -40,50 +58,146 @@ void function_y(int y) } ``` -### Variable Naming -Variables and function names must be in `snake_case` -``` c -void function_a(void); -void function_b(void); -``` -``` c +### Variable and Function Naming + +* Use `snake_case` for all variable and function names. + +**Examples**: + +```c int some_variable = 2; float other_variable = 5; + +void do_something(void); ``` +### Header Guards + +If you create a header file, use header guards: + +```c +#ifndef HEADER_NAME_H +#define HEADER_NAME_H + +// content + +#endif /* HEADER_NAME_H */ +``` + +### Line Length + +* Keep lines under **100 characters** when possible to improve terminal readability. + +### Whitespace + +* No trailing whitespace. +* One blank line between function definitions. +* Avoid unnecessary vertical spacing. + +### Include Order + +Organize includes like this: + +1. Corresponding header (if any) +2. Standard library headers +3. Other project headers + +--- + ## Build -- Make sure `make` succeeds with no warnings on your system -- Don't commit any build artifacts or backup files -- Test your changes on **multiple monitors (Xephyr)** +* `make` must succeed **with no warnings** on your system. +* Don’t commit build artifacts (e.g., `.o`, `sxwm`) or backup files (e.g., `*~`). +* Test your changes, especially on **multi-monitor setups** using **Xephyr**. + +--- + +## File Layout -## File Layouts +* Don’t create new `.c` or `.h` files unless absolutely necessary. +* Keep most changes within `sxwm.c` to maintain cohesion. -- Please try to not make a new C file or header unless it is necissary. Most of the codebase is kept in the `sxwm.c` file. +--- ## Submitting Changes -- Open a pull request with a **clear report** of the change(s) -- Keep commits having one purpose per commit -- If you fix a bug, please describe how to reproduce it -- If adding a feature, make sure it is consistent with sxwm’s minimalist philosophy -- Please don't keep multiple changes in one PR. Open a new one for that +* Open a pull request with a **clear description** of what and why. +* Keep **one purpose per commit** — don’t mix unrelated changes. +* If fixing a bug, describe **how to reproduce it**. +* If adding a feature, ensure it fits with `sxwm`’s **minimalist philosophy**. +* **Open separate PRs** for unrelated changes. + +--- + +## Git Commit Guidelines + +* Use imperative mood: `Add foo`, not `Added foo`. +* Keep the summary under 50 characters. +* Add a detailed body if needed. + +**Example**: + +``` +Fix crash when window is closed + +Previously, sxwm would segfault if a client closed itself. +This patch adds a check for null pointers before accessing window data. +``` + +--- + +## Tooling & Analysis + +* Use the provided `.clang-format` file where applicable. +* You may optionally run: + + * `cppcheck` + * `clang-tidy` +* Avoid committing debug code like stray `printf()` or `fprintf(stderr, ...)`. + +--- + +## Editor Configuration + +A sample `.editorconfig` file is provided (or you can request one). +It ensures editors match the project’s formatting conventions. + +--- ## Documentation -- If applicable, **update `sxwm.1`, `README.md` and `default_sxwmrc`**, update `CHANGELOG.md` +Update all relevant documentation if applicable: + +* `sxwm.1` +* `README.md` +* `default_sxwmrc` +* `CHANGELOG.md` + +--- ## Respect the Existing Structure -- Before large changes, open an issue discussion -- Please don’t change for style unless it improves clarity or fixes a problem +* For **large changes**, open an issue for discussion first. +* Do not change code for personal style unless it improves clarity or solves a specific problem. + +--- + +## Testing Checklist + +Please ensure the following before opening a PR: + +* [x] Code builds **without warnings** +* [x] Changes are **fully tested** +* [x] PR includes a **clear explanation** +* [x] Configuration reload works (if relevant) + +--- -## Testing +## Code Review Etiquette -- [x] Builds with no warnings -- [x] Tested to work fully -- [x] All changes are explained in the PR -- [x] Configuration reload works (if relevant) +* Be respectful and open to feedback. +* Feel free to ask questions about any review comments. +* Reviews are collaborative and meant to improve the code, not criticize you personally. --- |