Skip to content

Commit 7a5db62

Browse files
jonsedarfonnesbeck
jonsedar
authored and
fonnesbeck
committed
+ reformat README.rst (pymc-devs#720)
+ reformat CONTRIBUTING.md
1 parent 97571d3 commit 7a5db62

File tree

2 files changed

+146
-83
lines changed

2 files changed

+146
-83
lines changed

‎CONTRIBUTING.md

+88-59
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,44 @@
11
# Guidelines for Contributing
22
As part of the PyMC3 library documentation, the guidelines to contribute to
3-
pymc-examples are based on [PyMC3 contributing guidelines](https://github.com/pymc-devs/pymc3/blob/master/CONTRIBUTING.md). Please refer there
4-
for a detailed description of the Fork-PR contributing workflow, see "Steps" section,
5-
and note that you'll need to update the repository URLs and branch names.
3+
pymc-examples are based on
4+
[PyMC3 contributing guidelines](https://github.com/pymc-devs/pymc3/blob/master/CONTRIBUTING.md).
5+
Please refer there for a detailed description of the Fork-PR contributing workflow,
6+
see "Steps" section,and note that you'll need to update the repository URLs and
7+
branch names.
68

7-
This document therefore covers only some specific guidelines specific to this repository, mainly,
8-
an adapted version of the "Pull Request Checklist" and some extra guidelines for
9-
efficient collaboration with Jupyter notebooks.
9+
This document therefore covers only some specific guidelines specific to this
10+
repository, mainly, an adapted version of the "Pull Request Checklist" and some
11+
extra guidelines for efficient collaboration with Jupyter notebooks.
1012

1113
## Before submitting a pull request
12-
The notebooks in pymc-examples are in the process of being updated and reexecuted.
13-
The main progress tracker is [this GitHub project](https://github.com/pymc-devs/pymc-examples/projects/1).
14+
The notebooks in `pymc-examples` are in the process of being updated and reexecuted.
15+
The main progress tracker is
16+
[this GitHub project](https://github.com/pymc-devs/pymc-examples/projects/1).
1417

1518
### About the notebook tracker project
16-
This project serves as both tracker and organizer of the work needed on each of the example notebooks in this repo.
17-
Each notebook will have its own issue where we can point out things to fix and discuss them.
18-
These issue tickets are placed on one of the columns in this project based on the state of the notebook:
19-
20-
* **To Do:** notebooks in this column are potentially outdated, run on v3, don't follow the style guide,
21-
don't use best practices when using PyMC...
22-
* **Best practices (v3):** notebooks in this column use ArviZ and PyMC v3 best practices.
23-
* **v4 (auto)**: Notebooks in this column have been updated and reexecuted with PyMC v4,
24-
but following v3 style and patterns, and are not taking advantage of the new features
25-
introduced in v4.
26-
* **Book style**: Notebooks in this column have had their content, style and formatting updated
27-
to take advantage of all the pymc-examples website features, but still need work
28-
on the code side (either because they still use v3 or because they use v4 but don't
29-
take advantage of its new features). There is a [webinar](https://pymc-data-umbrella.xyz/en/latest/webinars/contributing_to_documentation/index.html)
30-
about the pymc examples repo and contributing to it, part of the PyMC Data Umbrella series.
31-
* **Done:** notebooks in this column use ArviZ and have been updated and executed with pymc3 v4.
19+
This project serves as both tracker and organizer of the work needed on each of
20+
the example notebooks in this repo.
21+
Each notebook will have its own issue where we can point out things to fix and
22+
discuss them.
23+
These issue tickets are placed on one of the columns in this project based on
24+
the state of the notebook:
25+
26+
* **To Do:** notebooks in this column are potentially outdated, run on v3, don't
27+
follow the style guide, don't use best practices when using PyMC...
28+
* **Best practices (v3):** notebooks in this column use ArviZ and PyMC v3 best
29+
practices.
30+
* **v4 (auto)**: Notebooks in this column have been updated and reexecuted with
31+
PyMC v4, but following v3 style and patterns, and are not taking advantage of
32+
the new features introduced in v4.
33+
* **Book style**: Notebooks in this column have had their content, style and
34+
formatting updated to take advantage of all the pymc-examples website features,
35+
but still need work on the code side (either because they still use v3 or
36+
because they use v4 but don't take advantage of its new features). There is a
37+
[webinar](https://pymc-data-umbrella.xyz/en/latest/webinars/contributing_to_documentation/index.html)
38+
about the pymc examples repo and contributing to it, part of the PyMC Data
39+
Umbrella series.
40+
* **Done:** notebooks in this column use ArviZ and have been updated and
41+
executed with PyMC v4.
3242

3343
Therefore, all notebooks will be progressively updated along this path:
3444

@@ -38,8 +48,8 @@ To Do --> Best Practices (v3) --< >--> Done
3848
\ --> v4 (auto) -- /
3949
```
4050

41-
See https://github.com/pymc-devs/pymc-examples/wiki/Notebook-updates-overview for a more detailed
42-
description of what each of the statuses mean.
51+
See https://github.com/pymc-devs/pymc-examples/wiki/Notebook-updates-overview
52+
for a more detailed description of what each of the statuses mean.
4353

4454
Each pull request should update a single notebook 1-2 positions to the right.
4555
Before starting a work on a pull request look at the tracker issue of the
@@ -73,21 +83,24 @@ but not being receiving such ping does not mean you won't get unassigned.
7383
If you know you won't be able to work during two weeks but plan to
7484
continue your work afterwards, let us know by commenting when you'll be able
7585
to retake the work.
76-
Alternatively, you can also contact your reviewers on [Discourse](https://discourse.pymc.io/)
77-
78-
As for review timeline, while you may get some reviews in a few hours or even some minutes
79-
if we happen to be working on related things, _you should not expect that to be the norm_.
80-
You should expect to receive review(s) for your PRs in 1-2 days. If two and a half days
81-
after submitting you still have not received any comment, let us know (i.e. tag whoever
82-
opened the issue you are addressing in a new PR comment. If at any point we were
83-
overwhelmed by PRs and delay this timeline, we will comment on your PR with an estimate
84-
of when you can expect a proper review.
86+
Alternatively, you can also contact your reviewers on
87+
[Discourse](https://discourse.pymc.io/)
88+
89+
As for review timeline, while you may get some reviews in a few hours or even
90+
some minutes if we happen to be working on related things,
91+
_you should not expect that to be the norm_.
92+
You should expect to receive review(s) for your PRs in 1 - 2 days. If 2 1/2 days
93+
after submitting you still have not received any comment, let us know
94+
(i.e. tag whoever opened the issue you are addressing in a new PR comment).
95+
If at any point we were overwhelmed by PRs and delay this timeline, we will
96+
comment on your PR with an estimate of when you can expect a proper review.
8597

8698
### In the event of a conflict
8799
In the event of two or more people working on the same issue,
88100
the general precedence will go to the person who first commented in the issue.
89101
If no comments it will go to the first person to submit a PR for review.
90-
Each situation will differ though, and the core contributors will make the best judgement call if needed.
102+
Each situation will differ though, and the core contributors will make the best
103+
judgement call if needed.
91104

92105
### If the issue ticket has someone assigned to it
93106
If the issue is assigned then precedence goes to the assignee.
@@ -96,33 +109,49 @@ the ticket is open for all again and will be unassigned.
96109

97110
## Pull request checklist
98111

99-
We recommended that your contribution complies with the following guidelines before you submit a pull request:
112+
We recommended that your contribution complies with the following guidelines
113+
before you submit a pull request:
100114

101-
* Use the pull request title to describe the issue and mention the issue number in the pull request description. This will make sure a link back to the original issue is created. For example, use `Use ArviZ in sampler stats notebook` as a title and link to [#46](https://github.com/pymc-devs/pymc-examples/issues/46) in the description.
102-
* Please do not submit PRs that are not addressing an issue already present in the issue tracker.
103-
* If you want to add a new notebook and no issue related to it is present yet, open one so we can
104-
discuss the best way to add the content to the repo. We have an issue template for that.
115+
* Use the pull request title to describe the issue and mention the issue number
116+
in the pull request description. This will make sure a link back to the original
117+
issue is created. For example, use `Use ArviZ in sampler stats notebook` as a
118+
title and link to [#46](https://github.com/pymc-devs/pymc-examples/issues/46)
119+
in the description.
120+
* Please do not submit PRs that are not addressing an issue already present
121+
in the issue tracker.
122+
* If you want to add a new notebook and no issue related to it is present yet,
123+
open one so we can discuss the best way to add the content to the repo.
124+
We have an issue template for that.
105125

106-
* Prefix the title of incomplete contributions with `[WIP]` (to indicate a work in progress). WIPs may be useful to (1) indicate you are working on something to avoid duplicated work, (2) request broad review of functionality or API, or (3) seek collaborators.
126+
* Prefix the title of incomplete contributions with `[WIP]` (to indicate a work
127+
in progress). WIPs may be useful to (1) indicate you are working on something
128+
to avoid duplicated work, (2) request broad review of functionality or API,
129+
or (3) seek collaborators.
107130

108-
* Make sure to run the whole notebook sequentially on a fresh kernel. You can do that with the
109-
"Restart & Run All" option before saving.
131+
* Make sure to run the whole notebook sequentially on a fresh kernel. You can do
132+
that with the "Restart & Run All" option before saving.
110133

111-
* No `pre-commit` errors: see the [Jupyter Notebook style](https://github.com/pymc-devs/pymc3/wiki/PyMC3-Jupyter-Notebook-Style-Guide) (and [Python code style](https://github.com/pymc-devs/pymc3/wiki/PyMC3-Python-Code-Style)) page from our Wiki on how to install and run it.
134+
* No `pre-commit` errors: see the
135+
[Jupyter Notebook style](https://github.com/pymc-devs/pymc3/wiki/PyMC3-Jupyter-Notebook-Style-Guide)
136+
(and [Python code style](https://github.com/pymc-devs/pymc3/wiki/PyMC3-Python-Code-Style))
137+
page from our Wiki on how to install and run it.
112138

113-
* Indicate how are you aiming to update the notebook (i.e. what is the target end column in the tracker). The pull request template has a template for this.
139+
* Indicate how are you aiming to update the notebook (i.e. what is the target
140+
end column in the tracker). The pull request template has a template for this.
114141

115142
## Contributor guide
116-
In order to work and run the example notebooks you need to install the packages in
117-
`requirements-write.txt`. To see how the notebook looks rendered, you can follow
118-
the instructions in the following paragraph or open a PR to see the preview in
119-
readthedocs.
120-
121-
The markdown cells in the notebook can use MyST, a superset of CommonMark markdown. See
122-
https://myst-parser.readthedocs.io/en/latest/ and https://myst-nb.readthedocs.io/en/latest/
123-
for documentation on their features and syntax.
124-
125-
To generate the draft standalone notebook gallery, you need to have installed all the packages in
126-
`requirements-docs.txt` and to run `sphinx-build examples/ _build -b html` from the repository
127-
home directory. After building, you can see the preview of the docs
128-
by opening `_build/index.html` file with your browser.
143+
In order to work and run the example notebooks you need to install the packages
144+
in `requirements-write.txt`. To see how the notebook looks rendered, you can
145+
follow the instructions in the following paragraph or open a PR to see the
146+
preview in **readthedocs**.
147+
148+
The markdown cells in the notebook can use MyST, a superset of CommonMark markdown.
149+
See https://myst-parser.readthedocs.io/en/latest/ and
150+
https://myst-nb.readthedocs.io/en/latest/ for documentation on their features
151+
and syntax.
152+
153+
To generate the draft standalone notebook gallery, you need to have installed
154+
all the packages in `requirements-docs.txt` and to run
155+
`sphinx-build examples/ _build -b html` from the repository home directory.
156+
After building, you can see the preview of the docs by opening `_build/index.html`
157+
file with your browser.

0 commit comments

Comments
 (0)