phUML Fork me on GitHub

Contributing to phUML

Code of Conduct

This project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Workflow

  • Fork the project.
  • Make your bug fix or feature addition.
  • Add tests for it. This is important, so we don't break it in a future version unintentionally.
  • Send a pull request. Bonus points for topic branches.

Pull requests for bug fixes must be based on the current stable branch whereas pull requests for new features must be based on the master branch.

Git commit format

Commit messages must follow the Conventional Commits Specification which is enforced as a Git pre-commit hook via GrumPHP.

The allowed commit types are:

  • build for changes to Github Actions or Scrutinizer (CI Pipeline)
  • chore for changes to the configuration any of the code quality tools used by this project (PHPUnit, PHP CS Fixer, Rector, Composer Normalize, Composer Require Checker, etc.)
  • docs for updates or additions to the documentation
  • feat for new features
  • fix for a fix to an existing console command
  • refactor for refactoring changes
  • style for changes that only format code
  • test for tests only changes

It is recommended to follow the 7 rules of a good commit message.

Coding Guidelines

This project follows the coding standards proposed in PSR-12.

Run the following command if you modified either production code or tests.

make format

Make will run PHP CS fixer in both folders src and tests.

We also use Rector to automatically refactor test and production code.

make refactor

Using phUML from a Git checkout

The following commands can be used to perform the initial checkout of phUML:

git clone git://github.com/MontealegreLuis/phuml.git
cd phuml

Retrieve phUML's dependencies using Composer:

composer install

Running phUML's test suite

There's a group of tests that verify that the generated class diagrams did not change. There's a slight difference in the output between operating systems. It is recommended to run the whole test suite using the provided Docker container. In order to run the container you'll also need to have Docker Compose installed. The container mimics the environment in Github Actions. Please make sure the tests pass in the container, so you can be sure they will pass in Github Actions too.

You can run the tests as follows:

make test

make will run PHPUnit with the same options it runs in Github Actions inside the Docker container.

You can alternatively run the test suite without this group of tests in your local environment.

vendor/bin/phpunit --exclude-group=snapshot

You will need XDebug installed to be able to generate the code coverage report.

make coverage

Running the commands from the container

If you want to get the same output as in the screenshots shown in the documentation, use the Docker container in this repository.

Use the following make commands to create the files using the Docker container

$ make diagram ARGS="src example.png -p neato"
$ make stats ARGS="src example.gv"
$ make stats ARGS="src statistics.txt"

With these commands you can pass the options and arguments via the ARGS variable

Contributing to the documentation

The documentation of this package is generated by Couscous. You can install Couscous globally with the following commands.

$ curl -OS https://couscous.io/couscous.phar
$ chmod +x couscous.phar
$ sudo mv couscous.phar /usr/local/bin/couscous

Run the following command to preview your changes:

$ couscous preview

Reporting issues

Before opening a new ticket, please search through the existing issues.