Contributing to PyMD4C

Thank you for your interest in contributing to PyMD4C!

Reporting Issues

If you have found an issue with PyMD4C but do not have the time or do not feel comfortable making a fix yourself, feel free to submit an issue on GitHub.

All issues and bug reports are welcome, but there are a few things you can do to help things move more smoothly:

  • Mention what versions of Python and PyMD4C you have installed. If you are not sure, you can check with:

    python3 --version
pip show pymd4c

  • Describe the incorrect output/behavior you are observing and the output/behavior you expected.

  • If possible, provide sample Python code that reproduces the issue, or at the very least, mention which class and any options you were using.

  • If the issue happens with specific input, provide an example Markdown document (preferably less than 20 lines or so) that reproduces the issue.

  • Any other information you think might be relevant (e.g. error messages, stack traces, your OS and CPU architecture, etc., depending on the type of issue).

Of course, some of the above only applies to certain types of issues. For example, if you ran into an issue building PyMD4C from source, providing sample Python code and input do not make sense (but you would want to provide some of the extra information mentioned in the last bullet point).

But just to reiterate, all issues and bug reports are welcome, even if they are light on details.

Feature Requests

If there is a feature missing from PyMD4C that you would like to see added, feel free to submit an issue on GitHub for this as well.

If you feel ambitious, you can even implement the feature youself and submit a pull request. If you do so, make sure you read the section below.

Code Contributions

If you have code you would like to contribute, please feel free to submit a pull request on GitHub.

All code contributions are appreciated, but there are a few guidelines that make it more likely that a PR can be accepted:

  • Generally speaking, the master branch is reserved for released code only. Development happens on the dev branch. That is the branch you should start working from, and the branch you should submit pull requests to. (If you submit a pull request to master, we will change it to dev.)

  • The automated test suite should run when pull requests are submitted. If there are any problems, you should do your best to fix them (or explain why the test is flagging when it shouldn’t). Code that passes has a much higher chance of being accepted than code that fails. You can run the test suite locally with:

    pip install -U .[test]
flake8 setup.py md4c/
pytest -vv test/

  • Pay attention to code style. Flake8 runs as part of the test suite. #noqa is allowed, but with good reason.

  • If you add new functionality, it has a higher chance of being merged if you add additional documentation and tests for the new feature.

  • Pull requests need not be related to an existing issue, but if you submit one that is, you should reference the issue number somewhere in the pull request.

None of these are automatic deal breakers if you do not follow them, but following them does increase the chances of your pull request being accepted.

All merged code contributions will be mentioned in the CHANGELOG with attribution to the contributor.