You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -32,7 +32,10 @@ The second approach is making your contribution directly in the GitHub website.
32
32
33
33
## Forking the repository
34
34
35
-
Independently of the approach you choose, the first step is to fork the Python Packaging Guide repository into your personal GitHub space. To "fork" a repository in GitHub means to create a copy of the main repository, or repo, that you have complete control over and can modify as you see fit.
35
+
Independently of the approach you choose, the first step is to fork the Python Packaging Guide repository into your personal GitHub space.
36
+
You can do this by clicking the "Fork" button in the top right corner of the repository page.
37
+
38
+
[Learn more: Fork and Clone GitHub Repos](https://datascienceskills.org/lessons/git-github/git-intro/3-fork-clone/) is a good resource to learn more about forking.
An image showing how to preview changes in GitHub. The file content is displayed in a text editor. The preview changes tab is highlighted with a red rectangle.
84
+
```
52
85
53
86
### How to commit your changes
54
87
55
-
*__TODO__: This section should show how to commit changes via the GitHub interface.*
88
+
When you are done editing the file, scroll down to the bottom of the page. You will see a section called "Commit changes".
89
+
Here you can write a title and a description for your changes. Make sure to write a clear and concise title that describes the changes you made.
An image showing how to commit changes in GitHub. The commit message is displayed in a text editor. The commit changes section is highlighted with a red rectangle.
98
+
```
99
+
100
+
After writing your commit message, click the "Commit changes" button to save your changes.
56
101
57
102
## Contributing locally on your computer
58
103
59
104
### Clone your forked repository
60
105
61
-
*__TODO__: This section should show how to clone a repository from GitHub into your computer.*
106
+
To clone your forked repository to your computer, you need to copy the URL of your forked repository and run the following command in your terminal:
107
+
108
+
```bash
109
+
git clone <URL>
110
+
```
111
+
Replace `<URL>` with the URL of your forked repository. You can find the URL by clicking the green "Code" button on your forked repository page.
An image showing how to clone a repository in GitHub. The URL of the repository is displayed in a text editor. The code button is highlighted with a red rectangle.
120
+
```
62
121
63
122
### Create a new branch
64
123
65
-
*__TODO__: This section should show how to create a new branch.*
124
+
Before making any changes, you should create a new branch to work on. This will help keep your changes separate from the main branch and make it easier to submit a pull request.
125
+
126
+
To create a new branch, run the following command in your terminal:
127
+
128
+
```bash
129
+
git checkout -b <branch-name>
130
+
```
66
131
67
132
### Create a virtual environment
68
133
69
-
*__TODO__: This section should show how to create a virtual environment using venv.*
134
+
To build the guide locally, you need to create a virtual environment and install the dependencies. You can do this by running the following commands in your terminal:
135
+
136
+
-**On Windows**:
137
+
```bash
138
+
python -m venv .venv
139
+
.venv\Scripts\activate
140
+
```
141
+
142
+
- **On MacOS and Linux**:
143
+
```bash
144
+
python -m venv .venv
145
+
source .venv/bin/activate
146
+
```
70
147
71
148
### Install the development dependencies
72
149
73
-
*__TODO__: This section should show how to install the development dependencies defined in pyproject.toml.*
150
+
To install the development dependencies, run the following commandin your terminal:
151
+
152
+
```bash
153
+
python -m pip install -e .[dev]
154
+
```
74
155
75
156
### Commit your changes
76
157
77
-
*__TODO__: This section should describe how to commit from the command line.*
158
+
After making your changes, you need to commit them to your local repository. To do this, run the following commands in your terminal:
159
+
160
+
- To see the changes you made:
161
+
```bash
162
+
git status
163
+
```
164
+
- To add the changes to the staging area:
165
+
```bash
166
+
git add .
167
+
```
168
+
- To commit the changes:
169
+
```bash
170
+
git commit -m "Your commit message here"
171
+
```
172
+
Replace `"Your commit message here"` with a clear and concise message that describes the changes you made.
78
173
79
174
### How to build the guide locally
80
175
81
-
*__TODO__: This section should describe the different sessions in nox related to building the docs: docs, docs-test, docs-live. It should also show how to see the guide built locally, by opening the right file in the browser or using the live version from docs-live*
176
+
To build the guide locally, you can use the `nox` command. This will run the default `nox` session, which builds the guide and opens it in your browser.
177
+
178
+
To see the different sessions available, you can run the following commandin your terminal:
179
+
180
+
```bash
181
+
nox --list-sessions
182
+
```
183
+
There are different sessions in nox related to building the docs: `docs`, `docs-test`, `docs-live`. You can run them by specifying the session name after the `nox` command.
184
+
185
+
- `docs`: this session builds the guide and opens it in your browser.
186
+
```bash
187
+
nox -e docs
188
+
```
189
+
To see the guide built locally, open the file `_build/html/index.html`in your browser.
190
+
191
+
- `docs-test`: this session runs the tests for the guide.
192
+
```bash
193
+
nox -e docs-test
194
+
```
195
+
If the tests fail, you will see an error message in your terminal. You need to fix the errors before submitting your pull request.
196
+
197
+
- `docs-live`: this session builds the guide and opens it in your browser with live reloading.
198
+
```bash
199
+
nox -e docs-live
200
+
```
201
+
open the local version of the guide in your browser at ``localhost`` shown in the terminal.
82
202
83
203
### Before you submit your pull request
84
204
85
-
*__TODO__: This section should describe what steps a user should follow before submitting the pull request: build the docs, verify your changes look correct, etc.*
205
+
Before submitting your pull request, make sure to run the tests and check the formatting of your code.
206
+
207
+
```bash
208
+
nox -e docs-test
209
+
```
210
+
If the tests fail, you will see an error message in your terminal. You need to fix the errors before submitting your pull request.
211
+
Also make sure to check the formatting of your documentation by building the docs locally and checking that your changes look correct.
212
+
86
213
87
214
## Submitting a pull request with your contribution
88
215
89
216
### How to make a pull request
90
217
91
-
*__TODO__: This section should describe how to make a pull request in GitHub.*
218
+
1. To open a pull request on GitHub, navigate to the main page of your forked repository and click on the "Pull requests" tab.
An image showing the status of the checks in a pull request in GitHub. The checks are displayed in a table with a status icon next to each check. The checks are highlighted with a red rectangle.
258
+
```
259
+
If any of these checks fail, you will see an error message in your pull request. You need to fix the errors before your changes can be merged.
An image showing the status of the checks in a pull request in GitHub. The checks are displayed in a table with a status icon next to each check. The checks that failed and the details link are highlighted with a red rectangle.
268
+
```
269
+
270
+
To get more information about the errors, you can click on the "Details" link next to the failed check.
96
271
97
272
### What to expect from the review process
98
273
99
-
*__TODO__: This section should describe how review happens in GitHub, how see the comments, and how to submit changes (push a new branch)*
274
+
Once you submit a pull request, a maintainer of the repository will review your changes and provide feedback. The review process may involve:
275
+
276
+
- **Comments**: the reviewer may leave comments on your pull request to ask questions or provide feedback.
277
+
- **Suggestions**: the reviewer may suggest changes to your code or documentation.
278
+
- **Approvals**: once the reviewer is satisfied with your changes, they will approve the pull request.
279
+
280
+
You can make changes to your pull request by pushing new commits to the branch. The pull request will be updated automatically with your new changes.
281
+
282
+
Once your pull request is approved, it will be merged into the main branch and your changes will be included in the guide.
Copy file name to clipboardExpand all lines: tests/run-tests.md
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -122,7 +122,7 @@ We will focus on [Nox](https://nox.thea.codes/) in this guide. `nox` is a Python
122
122
```{admonition} Other automation tools you'll see in the wild
123
123
:class: note
124
124
125
-
- **[Tox](https://tox.wiki/en/latest/index.html#useful-links)** is an automation tool that supports common steps such as building documentation, running tests across various versions of Python, and more. You can find [a nice overview of tox in the plasmaPy documentation](https://docs.plasmapy.org/en/stable/contributing/testing_guide.html#using-tox).
125
+
- **[Tox](https://tox.wiki/en/latest/index.html#useful-links)** is an automation tool that supports common steps such as building documentation, running tests across various versions of Python, and more.
126
126
127
127
- **[Hatch](https://github.com/ofek/hatch)** is a modern end-to-end packaging tool that works with the popular build backend called hatchling. `hatch` offers a `tox`-like setup where you can run tests locally using different Python versions. If you are using `hatch` to support your packaging workflow, you may want to also use its testing capabilities rather than using `nox`.
0 commit comments