diff options
author | Mike Frysinger <vapier@gentoo.org> | 2016-10-06 14:09:40 -0400 |
---|---|---|
committer | Mike Frysinger <vapier@gmail.com> | 2016-10-09 16:24:38 -0400 |
commit | 7ce5aeafc52c8360e6b0fdcc848431dae8e30ca9 (patch) | |
tree | 87be1205ab8121ba2a829a5a085eb93415540de9 /CONTRIBUTING.md | |
parent | b6b44d962dc927882f8a9062f90348d0ab5303cd (diff) | |
download | libgd-7ce5aeafc52c8360e6b0fdcc848431dae8e30ca9.tar.gz |
CONTRIBUTING: fill out the style section
Diffstat (limited to 'CONTRIBUTING.md')
-rw-r--r-- | CONTRIBUTING.md | 73 |
1 files changed, 72 insertions, 1 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 48b608f..407072c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -64,4 +64,75 @@ Explain the problem and include additional details to help maintainers reproduce * **If you're reporting that libGD crashed**, include a crash report with a stack trace from the operating system. Include the crash report in the issue in a [code block](https://help.github.com/articles/markdown-basics/#multiple-lines), a [file attachment](https://help.github.com/articles/file-attachments-on-issues-and-pull-requests/), or put it in a [gist](https://gist.github.com/) and provide link to that gist. -This text has been largely inspired by the Atom contributing notes, which amazingly complete +This text has been largely inspired by the Atom contributing notes, which are amazingly complete. + + +## Styleguides + +These sections tend to bore people. But if you don't follow them, it slows +down reviews from developers (and tends to tire/annoy them). Please give it +a look over and feel free to ask questions. + +### Git Commit Messages + +Rather than duplicate a ton of great explanations, please read this site: +http://chris.beams.io/posts/git-commit/ + +Yes, it's long, but once you read and understand it once, it applies to +every git project out there, not just GD. + +In case that site is broken, here is an archived link: +http://web.archive.org/web/20160706012209/http://chris.beams.io/posts/git-commit/ + +### Coding standard + +#### Style + +First, coding style should be consistent. If you're modifying a file that +might not follow this section, stick with that file's style. If we want to +fix the style later, we can. + +As for the rest, TBD! + +#### Practices + +Check for invalid settings (where reasonable) and return an error directly. +Do not use `assert` and do not require the user to follow the documented API. +e.g. Check for `NULL` pointers, and check enum values are within range. The +GD library is used in a lot of hostile environments (like websites) and is +given hostile (user controlled) data. When GD mishandles memory, that can be +used to attack servers. When GD crashes (or calls `assert`), that can take +out a web session. + +#### Testing + +We love unit tests. Every bugfix, new API, etc... should include a test update +to make sure future work doesn't break things or regress. We want to fix bugs +just once, not over and over again. + +Note that we say "should". While we really like tests, we understand that not +all changes are trivial to verify. + +Some general guidelines: + +* Tests should be standalone: One test should test one thing only. +* Tests should be reproducible: Avoid relying on system settings like /etc. +* Tests must be fast: A good guideline is that they should take <1 second, + and must take <5 seconds. +* Tests must be documented: Just add a comment block to the top of the file + with a short description and any existing bugs/URLs. + +### Documentation Styleguide + +Do everything in markdown. It's readable even in plain text, and converts +well into other formats (e.g. HTML). The question is which flavor! + +For files that end in `.md`, use +[GitHub markdown](https://guides.github.com/features/mastering-markdown/). + +For API documentation (embedded in the code), we use +[Natural Docs](http://www.naturaldocs.org/). You can find more info about +it under the [docs/naturaldocs/](docs/naturaldocs/) subdirectory. + +Try to keep the file linewrapped to 80 cols. Sometimes you won't be able to +because of long strings (like links), and that's OK. |