Skip to content

Commit 529ff97

Browse files
committed
add contributing guide
1 parent a1a1e62 commit 529ff97

File tree

3 files changed

+104
-0
lines changed

3 files changed

+104
-0
lines changed

CONTRIBUTING.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Contributing Guide
2+
3+
Please read the [Contributing Guide](https://pyper-dev.github.io/pyper/docs/Resources/Contributing) on the docs site
Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
---
2+
title: Contributing
3+
parent: Resources
4+
layout: default
5+
nav_order: 1
6+
permalink: /docs/Resources/Contributing
7+
---
8+
9+
# Contributing
10+
{: .no_toc }
11+
12+
* TOC
13+
{:toc}
14+
15+
We welcome developers to contribute to this project!
16+
17+
This guide will take you through our contribution guidelines and best practices.
18+
19+
The Pyper repository is hosted on [GitHub](https://github.com/pyper-dev/pyper).
20+
We will assume familiarity with Git-based version control and making [pull requests](https://docs.github.com/get-started/exploring-projects-on-github/contributing-to-a-project).
21+
22+
## Typos
23+
24+
All typo fixes are welcome. Feel free to simply open a pull request.
25+
26+
## Bugs and Features
27+
28+
### Issues
29+
30+
We track all ongoing improvements through GitHub Issues. Start by opening a [new issue](https://github.com/pyper-dev/pyper/issues/new/choose) if one doesn't exist already.
31+
32+
After you have created the issue, or you have found another unassigned issue you would like to work on, please:
33+
* Assign yourself to the issue if you are a collaborator
34+
* OR post a comment asking to be assigned to the issue
35+
36+
### Testing
37+
38+
Assuming you have:
39+
40+
* Been assigned to an issue
41+
* Forked and cloned a copy of the repo
42+
* Made your changes to the source code
43+
44+
We'll want to make sure that tests are passing before pushing and merging these changes.
45+
If the changes you've made warrant writing additional tests, please consider doing so.
46+
47+
To set up the testing environment, install the test dependencies (within a virtual environment):
48+
49+
```console
50+
$ pip install -r tests/requirements.txt
51+
```
52+
53+
Test coverage is measured against Python 3.12 -- we are aiming for 100% code coverage at all times.
54+
Use `tox` to run all tests within a 3.12 environment and generate a coverage report:
55+
56+
```console
57+
$ tox -e 3.12
58+
```
59+
60+
Please also make sure that tests pass successfully for all supported versions.
61+
You can do this without configuring additional Python virtual environments by using [Docker](https://docs.docker.com/):
62+
63+
```console
64+
$ cd tests
65+
$ docker-compose up --build --detach
66+
```
67+
68+
You can verify that all tests have passed succesfully if each container exits with a status code of 0, or by inspecting the Docker logs.
69+
70+
### Documentation
71+
72+
If relevant, please update the documentation appropriately. Documentation source files are found at `/docs/src`. These consist of markdown files, served with Jekyll on Github Pages, using the [just-the-docs](https://github.com/just-the-docs/just-the-docs) theme.
73+
74+
If you would like to serve the documentation locally, you will need to:
75+
76+
* Install [Ruby](https://www.ruby-lang.org/en/documentation/installation/)
77+
* Install [bundler](https://bundler.io/) (environment manager for Ruby)
78+
79+
Install dependencies with:
80+
81+
```console
82+
$ cd docs
83+
$ bundle install
84+
```
85+
86+
Then run:
87+
88+
```console
89+
$ bundle exec jekyll serve
90+
```
91+
92+
This serves the documentation site locally at `http://localhost:4000`, where you can inspect your changes.
93+
94+

docs/src/docs/Resources/index.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
title: Resources
3+
nav_order: 5
4+
layout: page
5+
---
6+
7+
# Resources

0 commit comments

Comments
 (0)