-
Notifications
You must be signed in to change notification settings - Fork 189
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
DOCS add contributing guide and syntax summary (#18)
Also add labelled math to example.
- Loading branch information
1 parent
f1c348f
commit 4f5df00
Showing
5 changed files
with
96 additions
and
4 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,41 @@ | ||
# Contributing | ||
|
||
## Code Style | ||
|
||
Code style is tested using [flake8](http://flake8.pycqa.org), | ||
with the configuration set in `.flake8`, | ||
and code formatted with [black](https://github.com/ambv/black). | ||
|
||
Installing with `myst_parser[code_style]` makes the [pre-commit](https://pre-commit.com/) | ||
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: | ||
|
||
```shell | ||
>> cd myst_parser | ||
>> pre-commit install | ||
``` | ||
|
||
Optionally you can run `black` and `flake8` separately: | ||
|
||
```shell | ||
>> black . | ||
>> flake8 . | ||
``` | ||
|
||
Editors like VS Code also have automatic code reformat utilities, which can adhere to this standard. | ||
|
||
## Pull Requests | ||
|
||
To contribute, make Pull Requests to the `develop` 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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -34,6 +34,7 @@ maxdepth: 2 | |
caption: Contents | ||
--- | ||
syntax.md | ||
contributing.md | ||
``` | ||
|
||
```{toctree} | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters