Fabric8 Analytics

Landing page

Contributing to Fabric8-Analytics

First off, thanks for taking the time to contribute!

The following is a set of guidelines (not rules) for contributing to Fabric8-Analytics, which is hosted in the Fabric8-Analytics Organization on Github. These are just guidelines, not rules, use your best judgment and feel free to propose changes to this document in a pull request.


Submitting Issues

  • You can create an issue on any repo under fabric8-analytics Github org, include as many details as possible with your report
  • Include the behavior you expected and maybe other places you’ve seen that behavior


Submitting a Pull Request

Note: Every PR requires at least one review from at least one of the Core Reviewers member.

Before you submit your pull request consider the following guidelines:

  • Fork the repository and clone your fork

  • Make your changes in a new git branch:

       git checkout -b bug/my-fix-branch master
  • Create your patch, ideally including appropriate test cases
  • Include documentation that either describe a change to a behavior or the changed capability to an end user
  • Commit your changes using a descriptive commit message. If you are fixing an issue please include something like ‘this closes issue #xyz’
  • Make sure your tests pass! We use Jenkins CI for our automated testing

  • Push your branch to GitHub:

      git push origin bug/my-fix-branch
  • When opening a pull request, select the master branch as a base.
  • Mark your pull request with [WIP] (Work In Progress) to get feedback but prevent merging (e.g. [WIP] Update CONTRIBUTING.md)

  • If we suggest changes then:

    • Make the required updates

    • Push changes to git (this will update your Pull Request):

      • You can add new commit

      • Or rebase your branch and force push to your Github repository:

      git rebase -i master
git push -f origin bug/my-fix-branch


Merge Rules

  • Include unit or integration tests for the capability you have implemented
  • Include documentation for the capability you have implemented
  • If you are fixing an issue, include the issue number you are fixing
  • Python code should follow PEP8 conventions

Git Commit Messages

  • Use the present tense (“Add feature” not “Added feature”)
  • Use the imperative mood (“Move cursor to…” not “Moves cursor to…”)
  • Reference issues and pull requests liberally


Implementation details

API

  • Use hyphenation over underscore or camelCase (i.e. /my-awesome-endpoint)

  • Any API change requires RAML documentation to be created or updated (otherwise the change will not be merged)

  • Provide extensive examples for input and output

  • Payload transferred over API should be in JSON format (exceptions are possible - for example while transferring files) and has to be documented with JSON Schema and JSL, see existing schemas for workers and server

Language

  • Use Python 3 where possible with potential exceptions:

    • Ecosystem (Node.js, Ruby…) specific features which require parsing of the non-Python code

    • Specific use case where Python does not provide needed functionality, library, framework… - needs strong justification and approval from tech leads

Deployment


That’s it! Thank you for your contribution!