Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
107 lines (65 loc) · 4.07 KB

CONTRIBUTING.md

File metadata and controls

107 lines (65 loc) · 4.07 KB
Raw

Contributing Guidelines

Thank you for considering a contribution to Rubix ML. We believe that our contributors play the most important role in bringing powerful machine learning tools to the PHP language. Please read over the following guidelines so that we can continue to provide high quality machine learning tools that our users love.

Pull Request Checklist

Here are a few things to check off before sending in a pull request ...

  • Your changes pass static analysis
  • All unit tests pass
  • Your changes are consistent with our coding style
  • Do your changes require updates to the documentation?
  • Does an entry to the CHANGELOG need to be added?

New to pull requests? Github has a great howto to get you started.

Code Review

We use pull requests as an opportunity to communicate with our contributors. Oftentimes, we can improve code readability, find bugs, and make optimizations during the code review process. Every pull request must have the approval from at least one core engineer before merging into the main codebase.

Static Analysis

Static code analysis is an integral part of our overall testing and quality assurance strategy. Static analysis allows us to catch bugs before they make it into the codebase. Therefore, it is important that your updates pass static analysis at the level set by the project lead.

To run static analysis:

$ composer analyze

Unit Testing

New code will usually require an accompanying unit test. What to test depends on the type of change you are making. See the individual unit testing guidelines below.

To run the unit tests:

$ composer test

General Object Testing

Limiting tests to public methods is usually sufficient. It is also important to test for edge cases such as mistakes that the user might make to ensure they are handled properly.

Bugfix Testing

Bugs usually indicate an area of the code that has not been properly tested yet. When submitting a bug fix, please include a passing test that would have reproduced the bug prior to your changes.

Coding Style

Rubix ML follows the PSR-2 coding style with additional rules to keep the codebase clean and reduce cognitive load for our developers. A consistent codebase allows for quicker debugging and generally a more pleasant developer experience (DX).

To run the style checker:

$ composer check

To run the automatic style fixer:

$ composer fix

Benchmarks

Performance can be critical for scientific computing. To ensure that our users have the best experience, we benchmark every operation and use the information as a baseline to make optimizations. When contributing a new operation please include a benchmark.

To run the benchmarking suite:

$ composer benchmark

Extension Development

Tensor's object oriented API is implemented in a PHP extension. The API code is written in Zephir and the underlying optimizations are written in C. This lets us take advantage of high-level language features while delivering high performance. Composer commands in the development environment handle compiling both the Zephir and C code for you. For a more detailed setup you can consult the Zephir documentation.

To compile the extension:

$ composer compile

To remove all the files created during compilation:

$ composer clean

Compiling the Docs

We use Mkdocs and Mike to compile the markdown documents in the docs folder to a versioned static document site.

Make sure to have the following Python dependencies installed.

$ pip install mike mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin

To serve the documentation site locally for development you can run the following commands from the terminal. Then, you'll be able to view the docs by navigating to http://127.0.0.1:8000 in your browser.

$ mike deploy 'VERSION'

$ mike serve