Home

Submitting Contributions to the Project

Before contributing please review the contribution guide.

Before You Submit Your Pull Request

• Ensure your commit message is useful and properly formatted.
• There should optimally be only one commit. All of your intermediate work-in-progress commits should be squashed.
• Include unit tests to cover both positive and negative cases utilizing reasonable examples of input data.
• Run py.test to validate your code submission. Also run tests against any rules that are dependent upon your code.
• Run coverage tests to ensure that you are sufficiently testing your code: py.test cov=falafel
• Run flake8 in the project root directory to check all files for PEP8 compliance. In falafel project directory the file .flake8 configures the compliance checks that are performed.
• Make sure your code is sufficiently documented following the Sphinx Google style for documentation. Include:
  • example input data;
  • an Examples: sections showing examples of use and attribute data structure;
  • clear description of how to use the code, assuming user has some knowledge of the domain; and
  • be clear on what “empty” data (falsey data objects) represents.
• Check spelling in your documentation and comments:

  $ pylint --disable all --enable spelling --spelling-dict en_US --spelling-private-dict-file $HOME/my.dict module_filename.py

  You may have to install pylint, python-enchant and aspell-en in order to perform spell check. Also you will want to create your own dictionary ($HOME/my.dict) to add words like redhat that may not be in the default dictionary. You may also check your module documentation with pydoc module_name.
• Check your documentation by running the generation script and verifying that the generated documentation looks correct and is accurate.

  $ cd docs
  $ make clean html_debug
  $ cd _build/html
  $ firefox index.html

• If you are exposing an attribute of type defaultdict or any other data structure that would mutate as a side effect of accessing the object, consider converting to a different type, for example dict.

After Submission of Your Pull Request

Once you have submitted your pull request a member of the project will review your submission. You may also add one or more of your team members as reviewers to your pull request. Continuous integration tests will be run on your code when the pull request has been submitted. The following tests will run:

1. py.test will be executed for the project.
2. Documentation will be generated to check for any errors.
3. flake8 will be executed to check for PEP8 compliance.

If any of those tests fail you will receive a notification, and you will need to fix any problems before the pull request will be reviewed by the project team.

Review by the Project Team

One or more members of the project team will review your pull request and either provide feedback, or merge your request. If there are reviewers that have commented on your merge request you need to resolve those comments before the request can be merged.

If you make subsequent commits to the same pull request branch there is no need to squash subsequent commits, however multiple commits may be squashed when your request is merged. Upon successful merge the topic branch will be removed.

Checklist for Reviewers

• Checkout pull request. See Resources [1]
• Remove any pre-existing .pyc files from the project directory: find . -name '*.pyc' -delete.
• Run tests: py.test
• Run tests on any projects, such as Red Hat Insights Rules, that depend on this project. If the pull request has not been rebased against the master branch recently then you may need to locally merge the master branch into this pull request to perform these tests.
• Generate the documentation and review the rendered HTML in a browser to check for problems.
• Review code changes/additions to ensure the code follows good coding practices, is maintainable, and is performs the described functions.
• Review the commit history to determine if the pull request needs to be squashed during the merge.
• Add comments to the merge request if required.
• Merge the request when all comments have been resolved. Use the option to Squash and Merge if the request includes multiple commits.

Resources

[1]: Consider using Hub for Git to make working with GitHub repos easier.