Contribution Guide

Thank you for your consideration to contribute. This project is powered and driven by its users, and contributions are welcome and will be fully credited.

• Code of Conduct
• Versioning
• Coding Standards
• Git Branching Strategy
• Adding New Features
• Security Vulnerabilities
• Contribution Guides
  • Contribution General Guidelines
  • Contributing to the Apiato Project
  • Contributing to the Documentation
  • Contributing to the Code Generator
  • Making a new Release

Code of Conduct

Apiato follows the Contributor Covenant Code of Conduct.

Versioning

The project is versioned under the Semantic Versioning guidelines.

Coding Standards

The project is compliant with PSR-1 Coding Standard, PSR-2 Coding Style and some of the PSR-12 Styles.

As well as it is compliant with PSR-4 Autoloader. If you notice any compliance oversights, you can send a pull request to address this issue.

Git Branching Strategy

The master branch contains the upcoming Apiato release. While the other branches are for all the stable releases (7.0, 7.1, 8.0...).

Bug fixes should be sent to both (the latest stable branch) and to master branch, unless they fix features that exist only in the upcoming release, then they should only be sent to master.

Major new features (and big changes) should always be sent to the master branch, which contains the upcoming release.

Example:

Assuming that the current stable version is 8.0. The repository would have at least the following two branches master and 8.0.

If your PR contains a major change, or a braking change, or a new Container then it must be sent to master branch. If your PR fixes a bug in the existing stable release then it should be sent to the latest release branch 8.0.

If you always contribute to Apiato, it's better to use the master branch instead of the latest release branch, to always have the latest features and updates and would be good to merge the latest stable branch into your master from time to time, in case it has some bug fixes.

Adding New Features

If you have an idea for a new feature, it's a good idea to check out our issues or active pull requests first to see if the feature is already being worked on. If not, feel free to submit an issue first (proposing the new feature), asking whether the feature is beneficial to the project. Then go ahead and submit your PR to the master branch.

Security Vulnerabilities

If you discover a security vulnerability, please email [email protected].

---

Contribution Guides

Contribution General Guidelines

Important things to remember when contributing:

• Run tests first before writing any line of code, run the tests vendor/bin/phpunit, and make sure all the tests are passing in your machine.
• Keep your commits atomic Each commit should represent a single unit of change. (Also, remember to write helpful commit messages.)
• Write as many tests Your changes must be covered with Tests (Functional or Unit). (Code without tests could be accepted in some cases).
• Ensure updating the documentation the doc repo is there https://github.com/apiato/documentation.
• Submit one feature/change per pull request. If you have multiple features/changes you wish to submit, please break them up into separate pull requests.

Contributing to the Apiato Project

This guide will help you contribute to the Apiato project, while working on your personal project.

If you added a feature/function to your local project or created a useful container or fixed a bug. This guide will show you how to submit that change to Apiato.

SETUP

One time setup

In this scenario let's assume we have the following:

• Apiato # is the starter/framework project
• Project-A # your personal project your building on top of apiato

1. Create Project A from Apiato

If you want to fix a bug on the latest stable release your PR should be sent to the latest stable branch, thus you need to pull the latest stable release of Apiato.

composer create-project apiato/apiato project-a

If you want to add new features or do anything else, that should be added to the next stable release, you need to pull the master branch and submit your PR there.

composer create-project apiato/apiato project-a --stability=dev

2. Initialize git in Project A

git init

3.a) Set up your origin remote (to point to your project private repository url)

git remote add origin [email protected]:username/repo.git

if you already have origin remote then update it with

git remote set-url origin [email protected]:username/project-a.git

3.b) Set up an upstream remote (to point to your fork of the apiato repository)

assuming you already forked the repository

git remote add upstream [email protected]:username/apiato.git

Now you should have the following remotes:

git remote -vv
origin      [email protected]:username/project-a.git (fetch)
origin      [email protected]:username/project-a.git (push)
upstream    [email protected]:username/apiato.git (fetch)
upstream    [email protected]:username/apiato.git (push)

4. Do your first commit

git add . && git commit -m 'first commit'

5.a) Create apiato branch

git checkout -b apiato

5.b) Let the apiato branch track the upstream master branch

git checkout apiato

git branch --set-upstream-to upstream/master

Now you should have the following branches:

git branch -vv
 apiato           77b4d945 [upstream/master] ...
 master           77d302aa [origin/master] ...

USAGE (Contribution Steps)

Must do every time before you contribute

1. Update remotes (fetch)

git fetch --all

2. Go to the apiato branch

git checkout apiato

3. Sync apiato branch with upstream/master

git reset --hard upstream/master

4. Now you can cherry-pick the commits you'd like to contribute

4.a) First go to the apiato branch

git checkout apiato

4.b) Create a custom branch for your PR

git checkout -b feature-awesome (must be created from apiato)

4.c) Do the cherry-picking

git log master (copy the commit ID)

git cherry-pick {commit-ID}

(repeat for all commits you want to submit)

5. Push apiato branch to the upstream

git push upstream feature-awesome (replace feature-awesome with your custom branch name)

6. Create a Pull Request (PR) from your forked repository to the apiato official repository.

Make sure you create a PR from your custom branch feature-awesome to master (or the latest stable release).

We'll do our best to merge your PR in the shortest time possible. Thanks in advance :)

Checkout How to upgrade apiato.

Contributing to the Documentation

This documentation is built using Docusaurus 2, a modern static website generator.

The content lives in its own repository (apiato/documentation), in the docs/ folder.

All you have to do is navigate to docs/ folder, find the markdown .md file that you want to update (all files are named as they are in the site menu), update or add the text, the commit.

You do not need to build the site locally. Just edit the markdown files and submit your PR. GitHub will build the site for us.

Optionally, visit the (documentation repository) for more information on how to install it locally.

Contributing to the Code Generator

The Code generator is in /core/Generator. The Core is in its own repository.

Each component command, "Except the Containers Generator" must extend from the Apiato\Core\Generator\GeneratorCommand.php. This abstract class does all the work for you.

Add new component generator.

General Info: the only function that gets called whenever a command is executed is the handle() function. This function exists on the abstract class Apiato\Core\Generator\GeneratorCommand which does all the common job for all the generator commands. For better understanding of how things work. Make sure you read that function.

1 - Add create new command by copying and pasting any of the existing components commands already supported. The Generator/Commands/RouteGenerator.php is a great example.

For each generator you need to implement exactly one method (as it is defined in the respective interface)

• getUserInputs: This method reads all parameters from the command line or provides a wizard to get information from the user. The available options for this generator are specified using the public $inputs = [] variable in respective generator. Note that you do not need to specify the options for --container or --file, as both are handled directly by the Generator itself. Simply add the options that are specifically needed for this generator.

  Be sure to read input with the checkParameterOrXYZ() methods, as they automatically check if an option is available. Otherwise, they will ask the user for additional input.

  The method must return an array of 3 keys:

  • path-parameters are used to replace variables within the path where the generator creates the file.
  • file-parameters are used to replace variables within the name of the file to be created.
  • stub-parameters are used to replace variables within the stub.

2 - Create the stub to be loaded in Generator/Stubs, copy any real component code and build the stub out of it.

3 - Finally register the command in Generator/GeneratorsServiceProvider.php using registerGenerators, example:

        $this->registerGenerators([
            ActionGenerator::class,
            RouteGenerator::class,
            TaskGenerator::class,
            // ...
        ]);

4 - Default FileName & FileExtension(optional)

You may provide another default filename or extension by overriding the getDefaultFileName() or getDefaultFileExtension() method, which simply returns a string.

Making a new Release (for admins)

1 - Merge the last stable branch in the master branch. (To get any new bug fixes.) 2 - Decide on the next version number for the new release. By checking the current releases. 3 - Update VERSION value in /core/Foundation/Apiato.php (example: const VERSION = '8.1.0';).

Minor Release

Your PR with that minor changes should be submitted and merged into master.

1 - Go to releases and create a new one from the master branch. 2 - Make sure you write a complete Changelog, in the release description. 3 - If you updated the documentation and you should! then visit the documentation repository and merge the PR into master.

Major Release

Master is the branch that contains all the new changes. So we need to create a new branch from master then make a release from that new branch.

1 - From master, checkout a new branch named as the version number you want to release. (Example 8.1). 2 - Go to releases and create a new one from the branch created in the step above. (Example 8.1). 3 - Make sure you write a complete Changelog, in the release description. 4 - Change the default branch on github to that new branch. 5 - If you updated the documentation and you should! then visit the documentation repository and merge the PR into master.