CONTRIBUTING.md

Contributing to gerb

Contributions are welcome and encouraged. They can be anything from spelling corrections, art, documentation, or source code fixes & additions. If a source code contribution is correct, functional and follows the code style and feature goals of the rest of the project, it will be merged.

Table of contents:

• Important links
• Developing environment
• Testing
• How to submit changes
• Choosing what to work on
• How to request an enhancement, new features
• Style Guide / Coding conventions
• Specific questions and answers
  • How do I include new images / icons?

Important links

• Main repository: https://github.com/epilys/gerb
• Bug/Issue tracker: https://github.com/epilys/gerb/issues
• Discussions: https://github.com/epilys/gerb/discussions

To privately contact the repository's owner, check their github profile for communication methods. You can also find email addresses in git commits.

^{_{back to top}}

Developing environment

You will need an operating system that is supported by gtk3 and rust. You can install rust and cargo with the rustup tool.

^{_{back to top}}

Testing

All tests can be executed with cargo. Run

cargo test

to run all tests.

^{_{back to top}}

How to submit changes

Use github's PR functionality. Alternatively, small patches can be emailed to the owner of the repository.

^{_{back to top}}

Choosing what to work on

You can find some tasks in the bug tracker. Additionally, tasks are annotated inside the source code with the keywords FIXME, TODO, needs_user_doc and others. For a list of all tags see src/lib.rs. To find tag references you can use a text search tool of your choice such as grep, ripgrep or others. The CLI tool tagref can also be used:

/path/to/gerb $ tagref list-refs
[ref:FIXME] @ ./src/utils.rs:106
[ref:FIXME] @ ./src/glyphs.rs:867
[ref:FIXME] @ ./src/project.rs:30
[ref:hardcoded_color_value] @ ./src/project.rs:411
...

You can of course filter or sort them by tag:

/path/to/gerb $ tagref list-refs | grep TODO
[ref:TODO] @ ./src/api/shell.rs:36
[ref:TODO] @ ./src/api/shell.rs:38
[ref:TODO] @ ./src/utils/range_query.rs:371
[ref:TODO] @ ./src/glyphs/obj.rs:304
/path/to/gerb $ tagref list-refs | sort -u
...

^{_{back to top}}

How to request an enhancement, new features

Simply open a new issue on the bug tracker. If you are uncertain if an enhancement would be appropriate or if you would like to request feedback you can alternatively post a thread in Discussions.

^{_{back to top}}

Style Guide / Coding conventions

All Rust code must be formatted by rustfmt, and python code by black.

^{_{back to top}}

Specific questions and answers

How do I include new images / icons?

First of all their format must be SVG. You can convert them to PNG with a simple command, that is wrapped in the script src/resources/svg_to_png.sh for convenience. You will need to install rsvg-convert. For optimizing PNG files you should use optipng. The location of all media resources must be in src/resources/.

^{_{back to top}}