Contributing to LacePHP
=======================

Thank you for considering a contribution to LacePHP! Whether you want to fix a bug, add a feature, improve performance or enhance the documentation, your help makes the framework stronger.

Why Contribute?
---------------
- **Improve** the tools you rely on.  
- **Give back** to the community.  
- **Learn** best practices in open-source PHP development.  

Getting Started
---------------
1. **Fork** the repository on GitHub:  
   https://github.com/OpenSourceAfrica/LacePHP  
2. **Clone** your fork locally:  

   .. code-block:: bash

      git clone git@github.com:<your-username>/LacePHP.git
      cd LacePHP

3. **Install** dependencies and tools:  

   .. code-block:: bash

      composer install
      npm install       # if docs use a local build tool

4. **Create** a feature branch:  

   .. code-block:: bash

      git checkout -b feature/describe-your-change

Code Contributions
------------------

Coding Standards
+++++++++++++++++

- Follow **PSR-12** (indent with 4 spaces, camelCase for methods, StudlyCaps for classes).  
- Keep methods short and focused (single responsibility).  
- Add or update **unit tests** for any new logic (use `phpunit`).  

Branch & Commit
+++++++++++++++++

- Use descriptive branch names: `feature/add-blueprint-support`, `bugfix/offsetget-type`  
- Write clear commit messages:  
  - Title (50 characters max)  
  - Blank line  
  - Detailed description if necessary  

Testing
++++++++

- Ensure **all tests pass** locally:  

  .. code-block:: bash

     vendor/bin/phpunit

- If you add new functionality, include tests under `tests/`.  

Pull Request
^^^^^^^^^^^^^
1. Push your branch to your fork:  

   .. code-block:: bash

      git push origin feature/describe-your-change

2. Create a **Pull Request** against the `main` branch of the upstream repo.  
3. In your PR description, explain:  
   - What problem you’re solving  
   - How you tested it  
   - Any backward-compatibility considerations  
4. Address review feedback by updating your branch; the PR will update automatically.

Documentation Contributions
---------------------------
Our docs live in **reStructuredText** under `manual/documentation/`. To improve them:

1. **Locate** the `.rst` file you wish to update (e.g. `routing.rst`, `models.rst`).  
2. **Edit** or **add** content following the existing style (headings, code blocks).  
3. **Build** the docs locally to preview (if you have Sphinx installed):  

   .. code-block:: bash

      pip install sphinx
      cd manual
      make html

   Then open `_build/html/index.html` in your browser.  
4. **Test** that your changes render correctly, with no syntax errors.  
5. **Commit**, push and open a PR as described above, referencing the documentation area.

Best Practices
--------------
- **One change per PR**: keep PRs focused.  
- **Reference issues**: if your work addresses a GitHub issue, mention it (`Fixes #123`).  
- **Be polite and patient**: maintainers are volunteers—reviews may take a little time.  

Code of Conduct
---------------
All contributors must adhere to our [Code of Conduct](https://github.com/OpenSourceAfrica/LacePHP/blob/main/CODE_OF_CONDUCT.md). Be respectful, inclusive and constructive in all communications.

Thank you for helping make LacePHP better!  

|
|