Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
131 lines (84 loc) · 3.26 KB

CONTRIBUTING.md

File metadata and controls

131 lines (84 loc) · 3.26 KB

Contributing Guidelines

Contributions are welcome and will be fully credited.

Please read and understand the contribution guide before creating an issue or pull request.

Code of conduct

Check the CODE OF CONDUCT.

Viability

When requesting or submitting new features, first consider whether it might be useful to others. Open source projects are used by many developers, who may have entirely different needs to your own. Think about whether or not your feature is likely to be used by other users of the project.

Filling an issue

Before filing an issue:

  • Attempt to replicate the problem, to ensure that it wasn't a coincidental incident.
  • Check the pull requests tab to ensure that the bug doesn't have a fix in progress.
  • Check to make sure your feature suggestion isn't already present within the project.
  • Check the pull requests tab to ensure that the feature isn't already in progress.

There are issue templates for bug reports, feature request and questions.

Creating a pull request

Before submitting a pull request:

  • Check the codebase to ensure that your feature doesn't already exist.
  • Check the pull requests to ensure that another person hasn't already submitted the feature or fix.
  • Check the issues list an relate your PR with an existing one. If there is not any, it may be useful to file a new one.
  • Create a new issue asking about implementing your feature if is not an small change.

Installing locally

Pre-installing requirements

Using Docker

If you don't have / want Composer and PHP installed in your local environment, you can use the configured Docker image for this.

For this, you will need to install Docker in your computer and build the image:

docker compose build

The image contains PHP 7.3, Node 16 and npm.

Then you can run docker compose run -it app bash and use php and npm as usual.

Without Docker

If you already have PHP and Node installed, you'll need:

  • PHP >= 5.6 <= 7.3
  • Node >= 8 <= 16
  • npm >= 7

Is recommended to use nvm to manage Node versions.

Installing dependencies

Make sure to install composer and npm dependencies.

composer install

# Or
# docker compose run -it app  composer install
npm install

# Or
# docker compose run -it app  npm install

Run docker compose run -it app bash to enter interactively to the docker shell.

You can also run

Building and previewing

First, start the pre-installed static http server:

docker compose up -d

Extract the PHP API docs:

# Each time demo files are changed
composer build:api-docs

# or
# docker compose run -it app  composer build:api-docs

Build the HTML files:

# After changing any .md file (including the one generated by build:api-docs-docs)
npm run docs:build

# or
# docker compose run -it app  npm run docs:build

Then, you can navigate to http://127.0.0.1:8089.

For development, auto-refreshing Vue files, use this instead:

npm run docs:dev

# or
# docker compose run -it -p 8080:8080 app  npm run docs:dev

There are some aliases for docker commands under .docker/ directory:

  • php
  • npm
  • composer
  • phpdoc

Example: .docker/composer install