Skip to content

Latest commit

 

History

History
90 lines (61 loc) · 4.94 KB

CONTRIBUTING.md

File metadata and controls

90 lines (61 loc) · 4.94 KB

Contribution Guidelines

Contributing

Contributions to Panko are released under the BSD-3-Clause license, the full text of which can be found in the LICENSE file.

The documentation is licensed under the Creative Commons CC-BY-SA 4.0 and can be found in the LICENSE.docs file

Development and Testing

As noted in the README, this project requires meson as it's build system. For a development setup, we recommend running meson setup --buildtype debugoptimized build rather than just meson setup. We also recommend the use of the 'build' directory name as this works with the existing .gitignore rules and keeps a nice commonality between all developer setups.

It is also recommended to enable asan and ubsan when doing development, you can enable them by running meson configure -Db_sanitize=address,undefined in the build directory. When the address sanitize is enabled, so is the leak sanitizer, however the stack traces it produces on exit can be incomplete. In order to see the full leak trace, export LSAN_OPTIONS=fast_unwind_on_malloc=0 into your build environment to have lsan produce full traces. It is also recommended to tell LSAN about the lsan_suppressions.txt file as to quiet it down about external leaks we can't do anything about by specifying suppressions=/path/to/lsan_suppressions.txt.

Common tasks

These are intended to be run from inside your build directory

  • Building the library component and tests: ninja (meson compile)
  • Running tests: ninja test (meson test), or to view the raw output meson test -v
  • Debugging tests: meson test --gdb

Fuzzing

If you are going to be running the fuzzing harnesses, then note the following dependencies are needed:

Both protobuf and libprotobuf-mutator will be handled by meson automatically when building.

Fuzzing is only supported using clang, as gcc does not have -fsanitize=fuzzer support which is needed.

To set up your fuzzing build directory, you can simply run the following from the source root:

$ CC=clang CXX=clang++ meson setup --buildtype debugoptimized -Db_sanitize=address,undefined build-fuzzing

The fuzzing_tests option is set by default, and so meson will handle all the setup for you.

Some changes occur in this configuration, b_lundef is set to false as that breaks clang linking the sanitizers, and also the b_sanitize option is modified to include linking to the fuzzer sanitizer.

Submitting a Pull Request

  1. Fork and clone the repository
  2. Create a new branch: git switch -c branch-name (git checkout -b branch-name in the old syntax)
  3. Make your change, create unit tests and sure all tests new and old pass
  4. Push to your fork and submit a pull request

Additionally, please write good and descriptive commit messages that both summarize the change and, if necessary, expand on the summary using description lines. "Patched the layout editor" is, while terse and correct, an example of a bad commit message. "Fixed a but in the layout editor preventing grid snapping from working properly" is an example of a better commit message.

We would like to be able to look back through the commit history and tell what happened, when, and why without having to dip into the commit descriptions as this improves the git bisect experience and improves everyone's lives.

We use rebasing to merge pull requests, so please keep this in mind and aim to keep a linear history.

Use of Generative AI

This project explicitly does not allow any contributions that were generated in whole or in-part by large language models (LLMs), chatbots, or image generation systems. This ban includes tools, including but not limited to Copilot, ChatGPT, Claude, DeepSeek, Stable Diffusion, DALL-E, Midjourney, or Devin AI.

This policy covers all parts of the project, including, but not limited to code, documentation, issues, artworks, comments, discussions, pull requests, and any other contributions to <PROJECT_NAME>, without exception.

Note

It is also recommended to avoid any and all AI tools when asking questions about <PROJECT_NAME>, prefer the documentation when available, as well as things such as the discussion forum, or IRC channel. These tools often fabricate plausible sounding information that is entirely incorrect, or often subtly incorrect and pass it off with confidence, thus misleading.