GitHub Repository

apiato

Thank you for considering to contribute to Apiato. This project is powered and driven by its users. So contributions are welcome and will be fully credited.

Standards and Practices

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 patch via pull request.

Git Branches

The master branch contains the upcoming Apiato release (in both repositories apiato/apiato and apiato/core). While the other branches are for the stable releases.

Bug fixes should be sent to the latest stable branch, never to the master branch, unless they fix features that exist only in the upcoming release.

Major new features should always be sent to the master branch, which contains the upcoming release.

Example:

Say we are in version 7.0 right now. The repository would have at least the following two branches master and 7.0 (possibly older branches as well such as 5.1, 5.0, 4.2, 4.1, 4.0 and so on). The latest stable branch in this case would be the 7.0. The next release will be 7.1 or 8.0.

If your PR contains a major change or a braking change, or new Container than it must be sent to the master branch. And if your PR fixes a bug, then it should be sent to the latest release branch.

If you would like to 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.

Proposing Feature

If you have a proposal or a feature request, you may create an issue with [Feature] tag in the title, example [Feature] Support XML responses.

The proposal should also describe the new feature, as well as implementation ideas. The proposal will then be reviewed and either approved or denied. Once a proposal is approved, a pull request may be created implementing the new feature.

Reporting Bugs

Bugs are tracked in our project’s issue tracker.

When submitting a bug report, please include enough information to reproduce the bug.

A good bug report includes the following sections:

Fixing Bugs

If you see a bug report that you’d like to fix, please feel free to do so. Following the directions and guidelines described in the “Adding New Features” section below, you may create bugfix branches and send us pull requests.

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, asking whether the feature is beneficial to the project. This will save you from doing a lot of development work only to have your feature rejected.

Contribution Guidelines

Important things to remember when contributing:

Security Vulnerabilities

If you discover a security vulnerability, please send email to mahmoud@zalt.me.



Contributing to Apiato

The project consist of 2 repositories apiato/apiato (the project skeleton, with default containers) and apiato/core (the core package of apiato).

Contributing to the Skeleton Project

The Apiato skeleton, is the actual Apiato project on the repository apiato/apiato.

This guide will help you contribute to the Apiato skeleton 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:

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 dev-master

2) Initialize git in Project A

git init

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

git remote add origin git@bitbucket.org:username/repo.git

if you already have origin remote then update it with

git remote set-url origin git@bitbucket.org:username/project-a.git

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

assuming you already forked the repository

git remote add upstream git@github.com:username/apiato.git

Now you should have the following remotes:

❯ git remote -vv
origin      git@bitbucket.org:username/project-a.git (fetch)
origin      git@bitbucket.org:username/project-a.git (push)
upstream    git@github.com:username/apiato.git (fetch)
upstream    git@github.com: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 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).

W’ll do our best to merge your PR in the shortest time possible. Thanks in advanced :)

Checkout How to upgrade apiato.


Contributing to the Core Package

The Apiato core package, is what provides most of the functionality of the Apiato project.

This guide will help you contribute to the Apiato core package, while the package is in your vendor directory. Without much effort.

SETUP

1) Delete the core package vendor/apiato/core from the vendor directory.

2) Pull the package to the project vendor (even if it was there) using:

composer update {your-username}/core --prefer-source

The composer option --prefer-source will clone the package’s git repository inside the vendor directory, so you can commit and push from the vendor directory directly.

3) Go to vendor/apiato/core/ from the terminal to access the package Git, in order to commit.

You should now have the .git directory of the core package (your forked version).

USAGE (Contribution Steps)

Edit > Commit > Push > PR :)


Contributing to the Documentation

The documentation is generated using Jekyll and lives in the documentation 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.

Documentation Tips:

Run the docs locally:

In Docker:

  1. git clone https://github.com/apiato/documentation .
  2. docker run -v $PWD:/srv/jekyll -p 4000:4000 -it jekyll/jekyll bash
  3. bundle install
  4. jekyll serve
  5. Browse http://localhost:4000

Natively:

  1. Install (Jekyll)[https://jekyllrb.com/] and its dependencies.
  2. git clone https://github.com/apiato/documentation .
  3. bundle install
  4. bundle exec jekyll serve
  5. Browse http://localhost:4000
  6. Finally jekyll build

Contributing to the Code Generator

The Code generator is part of the apiato/core package.

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 exist 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 copy 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)

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.