Skip to content

Contributing to Firefly III

Thank you so much for wanting to help make Firefly III better!

Please keep the following rules in mind, so we can both save a lot of time.

First, please familiarize yourself with the code of conduct, as it sets out general guidelines for interactions.

Pull requests for the main branch will be closed automatically.

What to be familiar with

This project is built using PHP8.5, Laravel, Twig, Javascript, HTML and CSS.

Fixing bugs

If you see a bug, and your first reaction is to open a PR, please describe the bug and its fix very carefully. When your fix requires a lot of changes, please let me know beforehand. I cannot accept new features out of the blue. Please first discuss the change you wish to make via issue, email, or any other method.

Listening and learning

For some people, getting a PR merged is like a badge of honor. Low effort PRs that fix spelling errors or change a single broken HTML tag will not be accepted. I'm afraid Firefly III can't be your learning experience. If you're new to all of this, please go be new somewhere else, thank you. Do not open PRs to "discuss" possible solutions or to "get feedback" on your code.

Code quality

Here are some guidelines to how I would like any set of commits to be. (I fully realize that I myself haven't always held myself to these standards, and there is a lot of code quality backfilling to be done.)

Documentability

Rather than leaving a TODO comment, open a new issue. The issue should be clear, contain some ideas about how things would be implemented, how it would fit in, what the requirements for completion of the issue is, and so on.

Any new functionality must be reflected with a functional test that demonstrates it is working. Any new functionality should also come with updates to the appropriate sections of the documentation.

Code should attempt to be self-documenting, but should also be commented to explain what's going on, at least at a high level.

Performance and complexity

One-liners or complex list/dict comprehensions are okay as long as they are clear and idiomatic. Please do not do nested comprehensions unless they are very simple and obvious; instead, split them out into separate, clear steps.

Any performance-optimization work should be done based on where optimization is needed, and it must show an actual measurable improvement. (Optimizing the clarity of code, on the other hand, is always welcome!)

Avoiding "unitaskers"

Functionality should only be added if it would potentially benefit everyone. With this in mind, any functionality that does only one specific thing should be made at least flexible or extensible enough that it can also do other, related things.

The API should be small and consistent and easy for anyone to use, or be easy for anyone to know where to look to understand something.

Test coverage

All new code should be tested in some way. Ideally this would be in the form of unit tests, but the reality is that much of Firefly III's functionality is difficult to unit test. All things should at least be manually tested with a repeatable procedure, and any tests for page-rendering functionality should be added into the local test site.

No AI contributions

This software is made by people, for people. While limited uses of AI can be helpful, the direct use of AI-generated code is an ethical and legal minefield. The current means by which models are trained puts an undue burden on the people, systems, and resources who are being exploited with vanishingly small returns on their efforts. Further, AI code is not generated with the context of the specific needs or design goals of a project.

Contributing to Firefly III requires human judgment, contextual understanding, and familiarity with Firefly III's structure and goals. It is not suitable for automatic processing by AI tools.

  • Refrain from submitting issues, pull requests or security advisories generated by any automated tools. I reserve the right, at my sole discretion, to close such submissions and to block any account responsible for them.
  • Do not paste AI generated text in the description of issues, PRs or in comments as this makes it harder for reviewers to assess your contribution. We are happy for it to be used to improve grammar or if you are not a native English speaker.

Behavior

Be prepared to answer whatever questions people might have about a contribution. Assume all questions are being made in good faith, and respond in kind.

The same goes for issues.

License

Your code will be licensed under the current Firefly III license. There are no exceptions, and you must be the sole writer of the code you submit. See also the earlier section titled "NO AI contributions."

Firefly III is a passion project, and I am only accepting submissions from people who are as passionate as me about this application. Your drive-by resume-filling PR will not be accepted.

Developer certificate of origin

Please read the developer certificate of origin and agree and comply with it.

Contributing text and documentation

If you see a spelling error, grammatical error or a weird translation in your language, please join our CrowdIn project. There, you can submit your translations and fixes. The GitHub repository will download these automatically, and they will be included in the next release.

Know that I am always open for rewrites and more clarity in the documentation, but I will not accept changes that people can Google themselves already. For example, do not submit text that explains how to set up Docker. Or how to install PHP.

Any documentation you write or fix must be checked for correct spelling. If you correct my spelling or grammar, you don't make mistakes of your own.

Is your language not listed? You can send your language to me by email or open a ticket on GitHub.

This guideline was inspired by the excellent Publ contribution policy and the contributing guidelines of the scikit-learn project.