Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
76 lines (55 loc) · 3.08 KB

CONTRIBUTING.md

File metadata and controls

76 lines (55 loc) · 3.08 KB

If you commit changes:

  1. Make sure all tests pass.
  2. Run mardown-it-bench, make sure that performance not degraded.

Other things:

  1. Prefer gitter for short "questions". Keep issues for bug reports, suggestions and so on.
  2. Make sure to read dev info prior to ask about plugins development.
  3. Provide examples with demo when possible.

Code Style

Code style is tested using flake8, with the configuration set in .flake8, and code formatted with black.

Installing with markdown-it-py[code_style] makes the pre-commit package available, which will ensure this style is met before commits are submitted, by reformatting the code and testing for lint errors. It can be setup by:

>> cd markdown-it-py
>> pre-commit install

Optionally you can run black and flake8 separately:

>> black .
>> flake8 .

Editors like VS Code also have automatic code reformat utilities, which can adhere to this standard.

All functions and class methods should be annotated with types and include a docstring. The prefered docstring format is outlined in markdown-it-py/docstring.fmt.mustache and can be used automatically with the autodocstring VS Code extension.

Testing

For code tests:

>> cd markdown-it-py
>> pytest

For documentation build tests:

>> cd markdown-it-py/docs
>> make clean
>> make html-strict
{ref}`develop/testing`

Pull Requests

To contribute, make Pull Requests to the master branch (this is the default branch). A PR can consist of one or multiple commits. Before you open a PR, make sure to clean up your commit history and create the commits that you think best divide up the total work as outlined above (use git rebase and git commit --amend). Ensure all commit messages clearly summarise the changes in the header and the problem that this commit is solving in the body.

Merging pull requests: There are three ways of 'merging' pull requests on GitHub:

  • Squash and merge: take all commits, squash them into a single one and put it on top of the base branch. Choose this for pull requests that address a single issue and are well represented by a single commit. Make sure to clean the commit message (title & body)
  • Rebase and merge: take all commits and 'recreate' them on top of the base branch. All commits will be recreated with new hashes. Choose this for pull requests that require more than a single commit. Examples: PRs that contain multiple commits with individually significant changes; PRs that have commits from different authors (squashing commits would remove attribution)
  • Merge with merge commit: put all commits as they are on the base branch, with a merge commit on top Choose for collaborative PRs with many commits. Here, the merge commit provides actual benefits.