Skip to content

Commit fd58704

Browse files
committed
Add pre-commit install instructions
1 parent 1de73f8 commit fd58704

File tree

1 file changed

+40
-36
lines changed

1 file changed

+40
-36
lines changed

CONTRIBUTING.md

Lines changed: 40 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Contributing
1+
# Contributing
22

33
## Installing development versions
44

@@ -17,45 +17,45 @@ poetry add git+https://github.com/pinecone-io/pinecone-python-client.git@44fc7ed
1717
```
1818

1919

20-
## Developing locally with Poetry
20+
## Developing locally with Poetry
2121

2222
[Poetry](https://python-poetry.org/) is a tool that combines [virtualenv](https://virtualenv.pypa.io/en/latest/) usage with dependency management, to provide a consistent experience for project maintainers and contributors who need to develop the pinecone-python-client
23-
as a library.
23+
as a library.
2424

25-
A common need when making changes to the Pinecone client is to test your changes against existing Python code or Jupyter Notebooks that `pip install` the Pinecone Python client as a library.
25+
A common need when making changes to the Pinecone client is to test your changes against existing Python code or Jupyter Notebooks that `pip install` the Pinecone Python client as a library.
2626

27-
Developers want to be able to see their changes to the library immediately reflected in their main application code, as well as to track all changes they make in git, so that they can be contributed back in the form of a pull request.
27+
Developers want to be able to see their changes to the library immediately reflected in their main application code, as well as to track all changes they make in git, so that they can be contributed back in the form of a pull request.
2828

29-
The Pinecone Python client therefore supports Poetry as its primary means of enabling a consistent local development experience. This guide will walk you through the setup process so that you can:
29+
The Pinecone Python client therefore supports Poetry as its primary means of enabling a consistent local development experience. This guide will walk you through the setup process so that you can:
3030
1. Make local changes to the Pinecone Python client that are separated from your system's Python installation
3131
2. Make local changes to the Pinecone Python client that are immediately reflected in other local code that imports the pinecone client
3232
3. Track all your local changes to the Pinecone Python client so that you can contribute your fixes and feature additions back via GitHub pull requests
3333

3434
### Step 1. Fork the Pinecone python client repository
3535

36-
On the [GitHub repository page](https://github.com/pinecone-io/pinecone-python-client) page, click the fork button at the top of the screen and create a personal fork of the repository:
36+
On the [GitHub repository page](https://github.com/pinecone-io/pinecone-python-client) page, click the fork button at the top of the screen and create a personal fork of the repository:
3737

3838
![Create a GitHub fork of the Pinecone Python client](./docs/pinecone-python-client-fork.png)
3939

40-
It will take a few seconds for your fork to be ready. When it's ready, **clone your fork** of the Pinecone python client repository to your machine.
40+
It will take a few seconds for your fork to be ready. When it's ready, **clone your fork** of the Pinecone python client repository to your machine.
4141

42-
Change directory into the repository, as we'll be setting up a virtualenv from within the root of the repository.
42+
Change directory into the repository, as we'll be setting up a virtualenv from within the root of the repository.
4343

44-
### Step 1. Install Poetry
44+
### Step 1. Install Poetry
4545

46-
Visit [the Poetry site](https://python-poetry.org/) for installation instructions.
46+
Visit [the Poetry site](https://python-poetry.org/) for installation instructions.
4747

48-
### Step 2. Install dependencies
48+
### Step 2. Install dependencies
4949

50-
Run `poetry install` from the root of the project.
50+
Run `poetry install` from the root of the project.
5151

5252
### Step 3. Activate the Poetry virtual environment and verify success
5353

54-
Run `poetry shell` from the root of the project. At this point, you now have a virtualenv set up in this directory, which you can verify by running:
54+
Run `poetry shell` from the root of the project. At this point, you now have a virtualenv set up in this directory, which you can verify by running:
5555

5656
`poetry env info`
5757

58-
You should see something similar to the following output:
58+
You should see something similar to the following output:
5959

6060
```bash
6161
Virtualenv
@@ -73,17 +73,21 @@ Path: /home/linuxbrew/.linuxbrew/opt/[email protected]
7373
```
7474
If you want to extract only the path to your new virtualenv, you can run `poetry env info --path`
7575

76-
## Loading your virtualenv in another shell
76+
### Step 4. Enable pre-commit hooks.
7777

78-
It's a common need when developing against this client to load it as part of some other application or Jupyter Notebook code, modify
79-
it directly, see your changes reflected immediately and also have your changes tracked in git so you can contribute them back.
78+
Run `poetry run pre-commit install` to enable checks to run when you commit so you don't have to find out during your CI run that minor issues need to be addressed.
8079

81-
It's important to understand that, by default, if you open a new shell or terminal window, or, for example, a new pane in a tmux session,
82-
your new shell will not yet reference the new virtualenv you created in the previous step.
80+
## Loading your virtualenv in another shell
81+
82+
It's a common need when developing against this client to load it as part of some other application or Jupyter Notebook code, modify
83+
it directly, see your changes reflected immediately and also have your changes tracked in git so you can contribute them back.
84+
85+
It's important to understand that, by default, if you open a new shell or terminal window, or, for example, a new pane in a tmux session,
86+
your new shell will not yet reference the new virtualenv you created in the previous step.
8387

8488
### Step 1. Get the path to your virtualenv
8589

86-
We're going to first get the path to the virtualenv we just created, by running:
90+
We're going to first get the path to the virtualenv we just created, by running:
8791

8892
```bash
8993
poetry env info --path
@@ -93,48 +97,48 @@ You'll get a path similar to this one: `/home/youruser/.cache/pypoetry/virtuale
9397

9498
### Step 2. Load your existing virtualenv in your new shell
9599

96-
Within this path is a shell script that lives at `<your-virtualenv-path>/bin/activate`. Importantly, you cannot simply run this script, but you
97-
must instead source it like so:
100+
Within this path is a shell script that lives at `<your-virtualenv-path>/bin/activate`. Importantly, you cannot simply run this script, but you
101+
must instead source it like so:
98102

99103
```bash
100104
source /home/youruser/.cache/pypoetry/virtualenvs/pinecone-fWu70vbC-py3.9/bin/activate
101105
```
102106
In the above example, ensure you're using your own virtualenv path as returned by `poetry env info --path`.
103107

104-
### Step 3. Test out your virtualenv
108+
### Step 3. Test out your virtualenv
105109

106-
Now, we can test that our virtualenv is working properly by adding a new test module and function to the `pinecone` client within our virtualenv
107-
and running it from the second shell.
110+
Now, we can test that our virtualenv is working properly by adding a new test module and function to the `pinecone` client within our virtualenv
111+
and running it from the second shell.
108112

109113
#### Create a new test file in pinecone-python-client
110-
In the root of your working directory of the `pinecone-python-client` where you first ran `poetry shell`, add a new file named `hello_virtualenv.py` under the `pinecone` folder.
114+
In the root of your working directory of the `pinecone-python-client` where you first ran `poetry shell`, add a new file named `hello_virtualenv.py` under the `pinecone` folder.
111115

112-
In that file write the following:
116+
In that file write the following:
113117

114118
```python
115119
def hello():
116120
print("Hello, from your virtualenv!")
117121
```
118-
Save the file.
122+
Save the file.
119123

120-
#### Create a new test file in your second shell
121-
This step demonstrates how you can immediately test your latest Pinecone client code from any local Python application or Jupyter Notebook:
124+
#### Create a new test file in your second shell
125+
This step demonstrates how you can immediately test your latest Pinecone client code from any local Python application or Jupyter Notebook:
122126

123-
In your second shell, where you ran `source` to load your virtualenv, create a python file named `test.py` and write the following:
127+
In your second shell, where you ran `source` to load your virtualenv, create a python file named `test.py` and write the following:
124128

125129
```python
126130
from pinecone import hello_virtualenv
127131

128132
hello_virtualenv.hello()
129133
```
130134

131-
Save the file. Run it with your Python binary. Depending on your system, this may either be `python` or `python3`:
135+
Save the file. Run it with your Python binary. Depending on your system, this may either be `python` or `python3`:
132136

133137
```bash
134138
python3 test.py
135139
```
136140

137-
You should see the following output:
141+
You should see the following output:
138142

139143
```bash
140144
❯ python3 test.py
@@ -154,7 +158,7 @@ Prerequisites:
154158
- You must have initialized the git submodules under codegen
155159

156160
```sh
157-
git submodule
161+
git submodule
158162
```
159163

160164

@@ -164,4 +168,4 @@ To regenerate the generated portions of the client with the latest version of th
164168

165169
```sh
166170
./codegen/
167-
```
171+
```

0 commit comments

Comments
 (0)