Skip to content

Latest commit

 

History

History
127 lines (91 loc) · 3.85 KB

contributing.rst

File metadata and controls

127 lines (91 loc) · 3.85 KB

Contributing

The client is an open source project under the BSD license. Contributions of any kind are welcome!

https://github.com/pycontribs/jira/

If you find a bug or have an idea for a useful feature, file it at the GitHub project. Extra points for source code patches -- fork and send a pull request.

Discussion and support

We encourage all who wish to discuss by using https://community.atlassian.com/t5/tag/jira-python/tg-p

Keep in mind to use the jira-python tag when you add a new question. This will assure that the project maintainers will get notified about your question.

Contributing Code

  • Patches should be:
    • concise
    • works across all supported versions of Python.
    • follows the existing style of the code base (PEP-8).
    • has comments included as needed.
  • Great Patch has:
    • A test case that demonstrates the previous flaw that now passes with the included patch.
    • Documentation for those changes to a public API

Testing

To test code run:

make test-all

This will run the code in a virtual environment, and will test across the versions of python which are installed. It will also install tox if it is not already installed.

Alternatively if you do not have make you can always run:

pip install tox
tox

Issues and Feature Requests

  • Check to see if there's an existing issue/pull request for the bug/feature. All issues are at https://github.com/pycontribs/jira/issues and pull requests are at https://github.com/pycontribs/jira/pulls.

  • If there isn't an existing issue there, please file an issue. The ideal report includes:

    • A description of the problem/suggestion.

    • How to recreate the bug.

    • If relevant, including the versions of your:

      • Python interpreter (2.7, 3.5, etc)
      • jira-python
      • Operating System and Version (Windows 7, OS X 10.10, Ubuntu 14.04, etc.)
      • IPython if using jirashell
      • Optionally of the other dependencies involved

    • If possible, create a pull request with a (failing) test case demonstrating what's wrong. This makes the process for fixing bugs quicker & gets issues resolved sooner.

    • Here is an template

      Description: <SUMMARIZE ISSUE>

Python Interpreter: <VERSION>
jira-python: <VERSION>
OS: <OPERATING SYSTEM>
IPython (Optional): <VERSION>
Other Dependencies:

Steps To Reproduce:
    1. <STEP>
    2. <STEP>
    3. <STEP>
    ...

Stack Trace:
    <TRACE>

Issues

Here are the best ways to help with open issues:

  • For issues without reproduction steps
    • Try to reproduce the issue, comment with the minimal amount of steps to reproduce the bug (a code snippet would be ideal).
    • If there is not a set of steps that can be made to reproduce the issue, at least make sure there are debug logs that capture the unexpected behavior.
  • Submit pull requests for open issues.

Pull Requests

There are some key points that are needed to be met before a pull request can be merged:

  • All tests must pass for all python versions. (Once the Test Framework is fixed)
    • For now, no new failures should occur
  • All pull requests require tests that either test the new feature or test that the specific bug is fixed. Pull requests for minor things like adding a new region or fixing a typo do not need tests.
  • Must follow PEP8 conventions.
  • Within a major version changes must be backwards compatible.

The best way to help with pull requests is to comment on pull requests by noting if any of these key points are missing, it will both help get feedback sooner to the issuer of the pull request and make it easier to determine for an individual with write permissions to the repository if a pull request is ready to be merged.