"Fossies" - the Fresh Open Source Software Archive

Member "libgd-2.3.3/CONTRIBUTING.md" (11 Sep 2021, 8361 Bytes) of package /linux/www/libgd-2.3.3.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format (assuming markdown format). Alternatively you can here view or download the uninterpreted source code file. A member file download can also be achieved by clicking within a package contents listing on the according byte size field. See also the latest Fossies "Diffs" side-by-side code changes report for "CONTRIBUTING.md": 2.3.2_vs_2.3.3.

Contributing to libgd

👍🎉 First off, thanks for taking the time to contribute! 🎉👍

Table Of Contents

What should I know before I get started?

How Can I Contribute?

Styleguides

What should I know before I get started?

Code of Conduct

This project adheres to the Contributor Covenant code of conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to security@libg.org.

Repositories

How Can I Contribute?

Documentation and examples

We have a relatively complete API documentation. However good documentation requires more than API docs. If you feel like writing tutorials, examples (C or other language binding) or add content to the documentation, you will be more than welcome.

We use NaturalDocs 1.5x for the API and general documentations. It supports rest, markdown or text (see the docs folder in our repository for examples).

Reporting Bugs or request a feature

This section guides you through submitting a bug or feature report for LibGD. Following these guidelines helps maintainers and the community understand your report 📝, reproduce the behavior 💻 💻, and find related reports 🔎.

Before creating bug reports, please check this list as you might find out that you don't need to create one. When you are creating a bug report, please include as many details as possible. If you'd like, you can use this template to structure the information.

Before Submitting A Bug Report

Before Submitting A feature Request

Please take the time to clearly describe what this feature should achieve. A good specification will help us to implement it, if it fits the roadmap.

We also have some open features, please check if the feature you would like to have is not already there. Maybe the specification can boost its implementation?

How Do I Submit A (Good) Bug Report?

For security related bugs, github does not support private issues, that's why we have to handle security issues outside the issues tracker for now. Please drop a mail to security@libg.org.

Bugs are tracked as GitHub issues. After you've determined which repository your bug is related to, create an issue on that repository and provide the following information.

Explain the problem and include additional details to help maintainers reproduce the problem:

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:

CI

If we are lucky enough to get pull request (PR) from you, we will do our best to support your efforts to get it in. As part of this, we setup a CI using github actions, which will be executed on new PR. Please check out the results of your PR to see if anything went wrong (it has Linux, MacOS and Windows OSes support). The CI must be green for a PR to be considered.

See [the github PR documentation]{https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request} for more details about how to create a pull request.

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.

For API documentation (embedded in the code), we use Natural Docs. You can find more info about it under the 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.