Skip to content

Commit a8afb0d

Browse files
committed
Update README.txt with tips for adding packages
1 parent c0e5191 commit a8afb0d

File tree

1 file changed

+59
-2
lines changed

1 file changed

+59
-2
lines changed

README.md

Lines changed: 59 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,9 +48,9 @@ If it is a more substantive change and you want to [install LoopDocs locally](#i
4848
# Run the next line **each time** you start a new shell window/tab
4949
source venv/bin/activate
5050
```
51-
- Install the project's required *Python* packages
51+
- **Install** the **dependencies** (that is the project's required *Python* packages)
5252
```shell
53-
cd loopdocs # Make sure you are in the folder where you cloned this repository
53+
cd loopdocs # where you cloned the loopdocs repository
5454

5555
python -m pip install -r dev-requirements.txt
5656
python -m pip install -r requirements.txt
@@ -612,3 +612,60 @@ The website uses the Markdown page of the glossary.
612612
> [!IMPORTANT]
613613
> Remember to commit these two files.
614614
615+
### Add a Package
616+
617+
> [!NOTE]
618+
> In this section, the terms Python **package** and **dependency** refer to the same thing.
619+
620+
- **Create** a feature **branch** (aka. topic branch)
621+
```shell
622+
git switch dev
623+
git switch -c feature/add_dependency_XXX
624+
```
625+
- **Add** the pinned version of the new **package** to the **`requirements.in`** file
626+
```shell
627+
MY_FAVORITE_EDITOR_HERE requirements.in
628+
629+
# Add the pinned version of the package to `requirements.in
630+
XXX_PACKAGE_NAME_HERE==XXX_PACKAGE_VERSION_HERE
631+
```
632+
For example, to add the `mkdocs-exporter` package version `6.1.1`, I added the following line to the `requirements.in` file:
633+
```text
634+
mkdocs-exporter==6.1.1
635+
```
636+
- Generate **`requirements.txt`**
637+
```shell
638+
cd loopdocs
639+
640+
# IMPORTANT: The project's virtual environment MUST be activated first
641+
source venv/bin/activate
642+
643+
# Remove the already installed packages in case you need to start from a blank slate
644+
# python -m pip freeze --exclude-editable | xargs python -m pip uninstall -y
645+
646+
# Install the development packages
647+
# (among which `pip-tools` that contains `pip-compile`)
648+
pip install -r dev-requirements.txt
649+
650+
# Install the direct dependencies (listed in `requirements.in`
651+
# This also installs the indirect dependencies these packages depend upon.
652+
pip install -r requirements.in
653+
654+
# Add code/doc using this package and test until it is ready.
655+
656+
# Generate the `requirements.txt` file from `requirements.in`
657+
# This can be slow, be patient
658+
pip-compile requirements.in
659+
660+
# Commit the changes (where XXX denotes the package name)
661+
git add requirements.in requirements.txt
662+
git commit -m "➕ Add dependency: XXX"
663+
664+
# Push your feature branch to your `origin` repository
665+
git push -u origin feature/add_dependency_XXX
666+
```
667+
- [**Create a Pull Request**](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) with your changes:
668+
- Open your clone repository of `trio-docs` on *GitHub* (`https://github.com/YOUR_USERNAME/trio-docs`)
669+
- Click the `Pull Requests` tab
670+
- Click "`Compare & pull request`" in the yellow banner next to your branch name
671+

0 commit comments

Comments
 (0)