Skip to content

Commit 65b3d5d

Browse files
blink1073blink1073
authored
ARROW-225 Make a top level Contributing Guide (#202)
* ARROW-225 Make a top level Contributing Guide * add contributing guide * fix manifest * address review
1 parent dbd8616 commit 65b3d5d

File tree

8 files changed

+260
-132
lines changed

8 files changed

+260
-132
lines changed

‎bindings/python/CONTRIBUTING.md

Lines changed: 257 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,257 @@
1+
# Contributing to PyMongoArrow
2+
3+
Contributions to PyMongoArrow are always encouraged. Contributions can be as simple
4+
as minor tweaks to the documentation. Please read these guidelines
5+
before sending a pull request.
6+
7+
## Bugfixes and New Features
8+
9+
Before starting to write code, look for existing [tickets in our JIRA project](https://jira.mongodb.org/browse/ARROW)
10+
or [create one](https://jira.mongodb.org/browse/ARROW) for your specific issue or
11+
feature request. That way you avoid working on something that might not
12+
be of interest or that has already been addressed.
13+
14+
## Supported Interpreters
15+
16+
PyMongoArrow supports CPython 3.7+ and PyPy3.8+. Language features not
17+
supported by all interpreters can not be used.
18+
19+
## Style Guide
20+
21+
PyMongoArrow uses [Ruff](https://docs.astral.sh/ruff/) for formatting and linting, with a line length of 100.
22+
23+
## General Guidelines
24+
25+
- Avoid backward breaking changes if at all possible.
26+
- Write inline documentation for new classes and methods.
27+
- Write tests and make sure they pass (make sure you have a mongod
28+
running on the default port, then execute `tox -e test` from the cmd
29+
line to run the test suite).
30+
- Add yourself to doc/contributors.rst `:)`
31+
32+
## Authoring a Pull Request
33+
34+
**Our Pull Request Policy is based on this** [Code Review Developer
35+
Guide](https://google.github.io/eng-practices/review)
36+
37+
The expectation for any code author is to provide all the context needed
38+
in the space of a pull request for any engineer to feel equipped to
39+
review the code. Depending on the type of change, do your best to
40+
highlight important new functions or objects you've introduced in the
41+
code; think complex functions or new abstractions. Whilst it may seem
42+
like more work for you to adjust your pull request, the reality is your
43+
likelihood for getting a review sooner shoots up.
44+
45+
**Self Review Guidelines to follow**
46+
47+
- If the PR is too large, split it if possible.
48+
49+
- Use 250 lines of code (excluding test data and config changes) as a
50+
rule-of-thumb.
51+
52+
- Moving and changing code should be in separate PRs or commits.
53+
54+
- Moving: Taking large code blobs and transplanting
55+
them to another file. There\'s generally no (or very
56+
little) actual code changed other than a cut and
57+
paste. It can even be extended to large deletions.
58+
- Changing: Adding code changes (be that refactors or
59+
functionality additions/subtractions).
60+
- These two, when mixed, can muddy understanding and
61+
sometimes make it harder for reviewers to keep track
62+
of things.
63+
64+
- Prefer explaining with code comments instead of PR comments.
65+
66+
**Provide background**
67+
68+
- The PR description and linked tickets should answer the "what" and
69+
"why" of the change. The code change explains the "how".
70+
71+
**Follow the Template**
72+
73+
- Please do not deviate from the template we make; it is there for a
74+
lot of reasons. If it is a one line fix, we still need to have
75+
context on what and why it is needed.
76+
77+
- If making a versioning change, please let that be known. See examples below:
78+
79+
- `versionadded:: 3.11`
80+
- `versionchanged:: 3.5`
81+
82+
**Pull Request Template Breakdown**
83+
84+
- **Github PR Title**
85+
86+
- The PR Title format should always be
87+
`[JIRA-ID] : Jira Title or Blurb Summary`.
88+
89+
- **JIRA LINK**
90+
91+
- Convenient link to the associated JIRA ticket.
92+
93+
- **Summary**
94+
95+
- Small blurb on why this is needed. The JIRA task should have
96+
the more in-depth description, but this should still, at a
97+
high level, give anyone looking an understanding of why the
98+
PR has been checked in.
99+
100+
- **Changes in this PR**
101+
102+
- The explicit code changes that this PR is introducing. This
103+
should be more specific than just the task name. (Unless the
104+
task name is very clear).
105+
106+
- **Test Plan**
107+
108+
- Everything needs a test description. Describe what you did
109+
to validate your changes actually worked; if you did
110+
nothing, then document you did not test it. Aim to make
111+
these steps reproducible by other engineers, specifically
112+
with your primary reviewer in mind.
113+
114+
- **Screenshots**
115+
116+
- Any images that provide more context to the PR. Usually,
117+
these just coincide with the test plan.
118+
119+
- **Callouts or follow-up items**
120+
121+
- This is a good place for identifying "to-dos" that you've
122+
placed in the code (Must have an accompanying JIRA Ticket).
123+
- Potential bugs that you are unsure how to test in the code.
124+
- Opinions you want to receive about your code.
125+
126+
# Installing from source
127+
128+
## System Requirements
129+
130+
On macOS, you need a working modern XCode installation with the XCode
131+
Command Line Tools. Additionally, you need CMake and pkg-config:
132+
133+
``` bash
134+
$ xcode-select --install
135+
$ brew install cmake
136+
$ brew install pkg-config
137+
```
138+
139+
On Linux, installation requires gcc 12, CMake and pkg-config.
140+
141+
Windows is not yet supported.
142+
143+
## Environment Setup
144+
145+
First, clone the mongo-arrow git repository:
146+
147+
``` bash
148+
$ git clone https://github.com/mongodb-labs/mongo-arrow.git
149+
$ cd mongo-arrow/bindings/python
150+
```
151+
152+
Additionally, create a virtualenv in which to install `pymongoarrow`
153+
from sources:
154+
155+
``` bash
156+
$ virtualenv pymongoarrow
157+
$ source ./pymongoarrow/bin/activate
158+
$ pip install tox
159+
```
160+
161+
### libbson
162+
163+
PyMongoArrow uses
164+
[libbson](http://mongoc.org/libbson/current/index.html). Detailed
165+
instructions for building/installing `libbson` can be found
166+
[here](http://mongoc.org/libmongoc/1.21.0/installing.html#installing-the-mongodb-c-driver-libmongoc-and-bson-library-libbson).
167+
168+
You can either use a system-provided version of `libbson` that is
169+
properly configured for use with `pkg-config`, or use the provided
170+
`build-libbson.sh` script to build it:
171+
172+
``` bash
173+
$ LIBBSON_INSTALL_DIR=$(pwd)/libbson tox -e build-libbson
174+
```
175+
176+
On macOS, users can install the latest `libbson` using Homebrew:
177+
178+
``` bash
179+
$ brew install mongo-c-driver
180+
```
181+
182+
Conda users can install `libbson` as follows:
183+
184+
``` bash
185+
$ conda install --channel conda-forge libbson pkg-config
186+
```
187+
188+
The minimum required version is listed in `pymongoarrow/version.py`. If
189+
you try to build with a lower version a `ValueError` will be raised.
190+
191+
## Build
192+
193+
Typically we will use the provided `tox` scripts and will not build
194+
directly, but you can build and test in the created virtualenv.
195+
196+
In the previously created virtualenv, to install PyMongoArrow and its
197+
test dependencies in editable mode:
198+
199+
``` bash
200+
(pymongoarrow) $ pip install -v -e ".[test]"
201+
```
202+
203+
If you built libbson using the `build-libbson` script then use the same
204+
`LIBBSON_INSTALL_DIR` as above:
205+
206+
> (pymongoarrow) \$ LIBBSON_INSTALL_DIR=\$(pwd)/libbson pip install -v
207+
> -e ".\[test\]"
208+
209+
## Test
210+
211+
To run the test suite, you will need a MongoDB instance running on
212+
`localhost` using port `27017`. To run the entire test suite, do:
213+
214+
``` bash
215+
(pymongoarrow) $ tox -e test
216+
```
217+
218+
or, if not using `tox`:
219+
220+
> (pymongoarrow) \$ pytest
221+
222+
## Running Linters
223+
224+
PyMongoArrow uses [pre-commit](https://pypi.org/project/pre-commit/) for
225+
managing linting of the codebase. `pre-commit` performs various checks
226+
on all files in PyMongoArrow and uses tools that help follow a
227+
consistent code style within the codebase.
228+
229+
To set up `pre-commit` locally, run:
230+
231+
``` bash
232+
(pymongoarrow) $ pip install pre-commit
233+
(pymongoarrow) $ pre-commi t install
234+
```
235+
236+
To run `pre-commit` manually, run:
237+
238+
``` bash
239+
(pymongoarrow) $ tox -e lint
240+
```
241+
242+
## Running Benchmarks
243+
244+
### System Requirements
245+
246+
To run the benchmarks, you need the [asv](https://pypi.org/project/asv/)
247+
package, which can then be invoked like so:
248+
249+
``` bash
250+
asv run --strict --python=`which python`
251+
```
252+
253+
or you can run with tox as:
254+
255+
``` bash
256+
tox -e benchmarks
257+
```

‎bindings/python/MANIFEST.in

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
include README.md
2+
include CONTRIBUTING.md
23
include LICENSE
34
include *.sh
45
include pyproject.toml

‎bindings/python/README.md

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -69,8 +69,7 @@ Note: `pymongoarrow` is not supported or tested on big-endian systems
6969

7070
## Development Install
7171

72-
See the instructions on [Read the
73-
Docs](https://mongo-arrow.readthedocs.io/en/latest).
72+
See the instructions in the [Contributing Guide][./CONTRIBUTING.md]
7473

7574
## Documentation
7675

‎bindings/python/docs/source/developer/benchmarks.rst

Lines changed: 0 additions & 16 deletions
This file was deleted.

‎bindings/python/docs/source/developer/index.rst

Lines changed: 0 additions & 10 deletions
This file was deleted.

0 commit comments

Comments
 (0)