Contribution to InvoicePlane
Every help is welcome, you don't have to be a professional PHP developer or SQL database engineer. We appreciate any support with helping other users, translating the software or simply spreading the word. You can find more general information in our community contribution guide.
If you have any questions regarding contribution please ask! Nothing is more frustrating for you
and us than misunderstandings which may lead to large amounts of time required to solve the resulting
We have a community forum and a Slack channel so please use them:
- Development Guidelines
- Versioning and Git Branches
- Getting Started with Development
- Contributing Code
To make sure the code is readable and well structured please follow these guidelines. We do highly recommend using the PhpStorm IDE as it natively supports the correct code formatting.
All code is formatted according to PSR-1 and PSR-2. These two standards assure that
the whole code looks the same and is well formatted.
Variables and functions are always declared in the
$under_score formatting, not
$camelCase. Arrays are always specified in the short syntax:
All CSS styles are written in Sass in the SCSS style. You
do not need to specify any styles with vendor prefixes like
they are added automatically in the compilation process!
Versioning and Git Branches
We do use SemVer to version InvoicePlane which means:
- Bugfixes or smaller improvements go into minor versions like
- New features or larger improvements go into feature versions like
The InvoicePlane branch structure consists of four different branch types
masterThis branch contains the current stable version of the application. There will never be any development activity on this branch so please refrain from using it for pull requests.
1.5Branches that contain only a feature version of InvoicePlane, like
1.5are archive branches that contain the last stable release of that specific version.
v1.6.0Branches that contain a specific version number like
v1.5.4are the development branches. All new code is added to these branches ONLY. If you contribute any code make sure to select the correct branch. Remember: bugfixes and small improvements go into minor branches like
v1.5.4and new features or large improvements go into feature branches like
issueOther named branches are used to keep code for very specific tasks that do not fit into another branch. Only push code to these branches if you are requested to do so.
Getting Started with Development
If you just want to change PHP code or HTML files, you just need to have
Composer installed. The tool manages
the PHP dependencies with the help of the
composer installto install all dependencies.
- Follow the basic installation guide in the README.md or the InvoicePlane Wiki.
- Make sure your editor or IDE has the correct code formatting settings set.
- That's it. You are good to go.
Styles and Scripts Development
To change the actual styling of the application or scripts you may have to install some other tools. Please notice that InvoicePlane has a unique theme system that splits up styles into core styles and theme styles. Please visit the InvoicePlane Themes repository for more information. This main repository ONLY manages core styles and scripts. If you want to develop a new theme please use the InvoicePlane Themes repository.
- InvoicePlane requires Node and NPM: Install both
Make sure to use the latest LTS version which is version 8 at the moment.
- Install Grunt globally by running
npm install -g grunt-cli.
If you have prepared your machine, run
npm install to install all dependencies.
After that there are two commands available for development:
grunt devCompiles all assets and starts watching your development files. If you change a file and save it, the compilation will start automatically so you do not have to do it manually. All styles and scripts are not minified and sourcemaps are generated for easier development.
grunt buildThis command is used to compile all assets for the production use. It also minifies all assets to make sure pages load faster. Normally this command is not used for development.
Read this carefully to prevent your pull request from being rejected!
Before you submit any code to the repository please take a look at the issue tracker and search for a corresponding issue! There should be no changes to the code without an issue filed.
- If an issue exists and someone is working on it, please contact this person.
- If an issue exists and no one is working on it, assign it to yourself or write a comment.
- If no issue exists, contact the InvoicePlane team via the forums or the Slack channel first! We would like to discuss what you want to do before you start to work.
ALWAYS reference the issue ID (e.g. IP-317) in all commits you create for this issue.
BEFORE you create a pull request, rebase from the corresponding branch. This is very important to make sure that there are no duplicate commits and you do not revert any previous changes.
- Add the development branch as a remote:
git remote add ip firstname.lastname@example.org:InvoicePlane/InvoicePlane.git
- Do a rebase with the following command:
git pull --rebase ip [branch]
ipis the name of the remote and
[branch]the corresponding branch.
- Solve all conflicts and check if your code is still working.
- Add the development branch as a remote:
Submit the pull request, reference the issue ID in the title and add a meaningful description.
Please ask questions related to this process if you are unsure. Asking before doing anything will save both your and our time.
The name 'InvoicePlane' and the InvoicePlane logo are both copyright by Kovah.de and InvoicePlane.com and their usage is restricted! For more information visit invoiceplane.com/license-copyright