Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
213 lines (145 loc) · 7.74 KB

CONTRIBUTING.md

File metadata and controls

213 lines (145 loc) · 7.74 KB
Raw

Contributing to InvoicePlane

Thank you for considering contributing to InvoicePlane! Your support is invaluable in improving and maintaining this project. Whether you're reporting bugs, suggesting features, writing code, or helping others, your contributions are welcome.

Table of Contents

  1. How Can I Contribute?
  2. Development Guidelines
  3. Getting Started with Development
  4. Community and Support
  5. Code of Conduct

How Can I Contribute?

Reporting Bugs

If you encounter a bug, please report it by opening an issue and include:

  • Description: A clear and concise description of the bug.
  • Steps to Reproduce: Detailed steps to reproduce the issue.
  • Expected Behavior: What you expected to happen.
  • Actual Behavior: What actually happened.
  • Screenshots: If applicable, add screenshots to help explain the problem.
  • Environment: Information about your environment (e.g., operating system, browser, InvoicePlane version).

Suggesting Features

To suggest a new feature, please open an issue and include:

  • Feature Description: A clear and concise description of the feature.
  • Use Case: Explain why this feature would be useful.
  • Additional Context: Any other context or screenshots that might help.

Code Contributions

If you'd like to contribute code:

  1. Fork the Repository: Click the "Fork" button at the top right of the repository page.
  2. Clone Your Fork: 
    git clone https://github.com/your-username/InvoicePlane.git
  3. Create a Branch: 
    git checkout -b feature/your-feature-name
  4. Make Your Changes: Implement your feature or fix.
  5. Commit Your Changes: 
    git commit -m "Brief description of your changes"
  6. Push to Your Fork: 
    git push origin feature/your-feature-name
  7. Open a Pull Request: Go to the original repository and open a pull request from your fork.

Please ensure your code adheres to the Development Guidelines and includes appropriate tests.

Documentation

Improving documentation is a valuable way to contribute. You can:

  • Enhance Existing Documentation: Clarify or expand upon current documentation.
  • Create New Guides: Write guides for new features or common tasks.
  • Fix Typos or Errors: Correct any mistakes you find.

To contribute to the documentation:

  1. Fork the Repository: As described above.
  2. Make Your Changes: Edit the relevant .md files.
  3. Open a Pull Request: As described above.

Translations

Help make InvoicePlane accessible to a global audience by contributing translations:

  • Check Existing Translations: See if your language is already supported.
  • Improve Translations: Enhance existing translations for clarity and accuracy.
  • Add New Translations: If your language isn't supported, consider adding it.

Please refer to the TRANSLATIONS.md for detailed instructions.

Community Support

Engage with the InvoicePlane community by:

Development Guidelines

Setting Up Your Development Environment

Follow the three-phase development workflow outlined in INSTALLATION.md:

Phase 1: Prepare (Initial Setup)

  1. Clone the Repository

    git clone https://github.com/InvoicePlane/InvoicePlane.git
cd InvoicePlane

  2. Install Dependencies

    composer install    # PHP dependencies
yarn install       # JavaScript dependencies
yarn build         # Build frontend assets

  3. Configure Application — only needed for docker-compose.yml below, and only if you want to set it up yourself (see Phase 2):

    cp ipconfig.php.example ipconfig.php

    Edit ipconfig.php with your database and URL settings.

Phase 2: StartMeUp (Launch Environment)

Two Docker setups are available — see resources/docker/README.md for the full comparison; pick whichever matches what you're doing:

  • compose.yml — self-contained, one command, good for quickly spinning up InvoicePlane to test something.
  • docker-compose.yml — separated php/nginx/db/phpmyadmin services that bind-mount your working tree, so PHP/frontend edits are reflected immediately without a rebuild. This is what you want for active development.
docker compose -f docker-compose.yml up -d --build

ipconfig.php is generated automatically on first run if you skipped step 3 above.

Add 127.0.0.1 ivpl.local to your /etc/hosts file first — the bundled nginx config expects that hostname (see resources/docker/README.md for why).

Access:

Phase 3: Workflow (Daily Development)

  1. Make changes to PHP or frontend files
  2. Rebuild assets if needed: yarn build or grunt watch
  3. Test changes at http://ivpl.local
  4. Run linters: composer check
  5. Commit and push your changes

For detailed workflow instructions, see INSTALLATION.md - Development Workflow.

Coding Standards

  • PHP: PSR-12 Standard
  • JavaScript: Standard JS Code Formatting

Testing

  • Testing is very much appreciated, especially during Beta phases. Click through all functionalities of the application and check if you see weird behavior (for example: uploads not working anymore after a new Beta version of InvoicePlane), mention it in the community (Discord, community.invoiceplane.com forums) and see if an issue should be made.

Branching Strategy

  • development Active development

  • bugfix/* For bug fixes. Please refer to an issue, if you have one.

  • feature/* New features. Please refer to an issue, if you have one.

  • master Stable releases. Every time a new version of InvoicePlane goes live, that same version is available in the master branch.

Community and Support

Code of Conduct

We follow a Code of Conduct to ensure a friendly and inclusive environment. By contributing, you agree to abide by these principles.

For full details, see CODE_OF_CONDUCT.md.

Happy Coding!