Skip to content

Commit 221246f

Browse files
redeboerredeboer
committed
DOC: update developer instructions
1 parent 279dd02 commit 221246f

2 files changed

Lines changed: 27 additions & 103 deletions

File tree

‎docs/develop.md‎

Lines changed: 26 additions & 102 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
This page describes some of the tools and conventions followed by
66
[Common Partial Wave Analysis](https://github.com/ComPWA). Where possible, we use the
7-
[source code of the AmpForm repository](https://github.com/ComPWA/AmpForm) as example,
7+
[source code of the AmpForm repository](https://github.com/ComPWA/ampaorm) as example,
88
because its file structure is comparable to that of other ComPWA repositories.
99

1010
:::::{tip}
@@ -30,14 +30,19 @@ pixi shell
3030
:::
3131
::::
3232

33-
Then, install the [`pre-commit`](https://pre-commit.com) and the hooks for this repository:
33+
In addition, [`pre-commit`](https://pre-commit.com) is used to enforce style checks and can be installed with::
3434

3535
```shell
36-
37-
uv tool install --with pre-commit-uv pre-commit
36+
uv tool install --python=3.13 --with pre-commit-uv pre-commit
3837
pre-commit install --install-hooks
3938
```
4039

40+
In `uv`-only projects, [Poe the Poet](https://poethepoet.natn.io) is used as task runner and can be installed with:
41+
42+
```shell
43+
uv tool install --python=3.13 poethepoet
44+
```
45+
4146
See {ref}`develop:Virtual environment` for more info.
4247
:::::
4348

@@ -145,15 +150,6 @@ the repository you want to work on, navigate into it, and run:
145150
python3 -m pip install -e .
146151
```
147152

148-
:::{toggle}
149-
Internally, this calls:
150-
151-
```shell
152-
python3 setup.py develop
153-
```
154-
155-
:::
156-
157153
This will also install all dependencies required by the package.
158154

159155
### Optional dependencies
@@ -191,49 +187,7 @@ requirements can be installed with the last example.
191187

192188
### Pinning dependency versions
193189

194-
To ensure that developers use exactly the same versions of the package dependencies and
195-
developer requirements, some of the repositories provide
196-
[constraint files](https://pip.pypa.io/en/stable/user_guide/#constraints-files). These
197-
files can be used to 'pin' all versions of installed packages as follows:
198-
199-
:::{margin}
200-
Requirements may differ per Python version, so there is one constraint file for each
201-
version of Python that the package supports.
202-
:::
203-
204-
```shell
205-
python3 -m pip install -c .constraints/py3.10.txt -e .
206-
```
207-
208-
The syntax works just as well for {ref}`develop:Optional dependencies`:
209-
210-
::::{tab-set}
211-
:::{tab-item} Bash
212-
213-
```shell
214-
python3 -m pip install -c .constraints/py3.10.txt -e .[doc,sty]
215-
python3 -m pip install -c .constraints/py3.10.txt -e .[test]
216-
python3 -m pip install -c .constraints/py3.10.txt -e .[dev]
217-
```
218-
219-
:::
220-
:::{tab-item} Z shell
221-
222-
```shell
223-
python3 -m pip install -c .constraints/py3.10.txt -e ".[doc,sty]"
224-
python3 -m pip install -c .constraints/py3.10.txt -e ".[test]"
225-
python3 -m pip install -c .constraints/py3.10.txt -e ".[dev]"
226-
```
227-
228-
:::
229-
::::
230-
231-
The constraint files are updated automatically with
232-
[`pip-tools`](https://github.com/jazzband/pip-tools) through
233-
{ref}`develop:GitHub Actions`. See
234-
[`requirements-pr.yml`](https://github.com/ComPWA/ampform/actions/workflows/requirements-pr.yml)
235-
and
236-
[`requirements-cron.yml`](https://github.com/ComPWA/ampform/actions/workflows/requirements-cron.yml).
190+
To ensure that developers use exactly the same versions of the package dependencies and developer requirements, some of the repositories provide lock files, such as [`uv.lock`](https://docs.astral.sh/uv/concepts/projects/sync) and [`pixi.lock`](https://pixi.prefix.dev/v0.63.2/workspace/lockfile). The constraint files are updated automatically with the [ComPWA/actions/.github/workflows/lock.yml](https://github.com/ComPWA/actions/blob/v4/.github/workflows/lock.yml) workflow using {ref}`develop:GitHub Actions`.
237191

238192
:::{note}
239193
Constraint files ensure that the framework is _deterministic and reproducible_ (up to
@@ -243,36 +197,6 @@ and for developers (for instance with
243197
way out of ["dependency hell"](https://en.wikipedia.org/wiki/Dependency_hell).
244198
:::
245199

246-
### Updating
247-
248-
It may be that new commits in the repository modify the dependencies. In that case, you
249-
have to rerun this command after pulling new commits from the repository:
250-
251-
::::{tab-set}
252-
:::{tab-item} Bash
253-
254-
```shell
255-
git checkout main
256-
git pull
257-
pip install -c .constraints/py3.10.txt -e .[dev]
258-
```
259-
260-
:::
261-
:::{tab-item} Z shell
262-
263-
```shell
264-
git checkout main
265-
git pull
266-
pip install -c .constraints/py3.10.txt -e ".[dev]"
267-
```
268-
269-
:::
270-
::::
271-
272-
If you still have problems, it may be that certain dependencies have become redundant.
273-
In that case, trash the virtual environment and
274-
{ref}`create a new one <develop:Virtual environment>`.
275-
276200
### Julia
277201

278202
[Julia](https://julialang.org) is an upcoming programming language in High-Energy
@@ -344,10 +268,10 @@ juliaup default release
344268

345269
```shell
346270
cd ~/Downloads
347-
tar xzf julia-1.10.3-linux-x86_64.tar.gz
271+
tar xzf julia-1.12.4-linux-x86_64.tar.gz
348272
mkdir ~/opt ~/bin
349-
mv julia-1.10.3 ~/opt/
350-
ln -s ~/opt/julia-1.10.3/bin/julia ~/bin/julia
273+
mv julia-1.12.4 ~/opt/
274+
ln -s ~/opt/julia-1.12.4/bin/julia ~/bin/julia
351275
```
352276

353277
Make sure that `~/bin` is listed in the `PATH` environment variable, e.g. by updating it
@@ -362,9 +286,9 @@ export PATH="~/bin:$PATH"
362286

363287
```shell
364288
cd ~/Downloads
365-
tar xzf julia-1.10.3-linux-x86_64.tar.gz
366-
sudo mv julia-1.10.3 /opt/
367-
sudo ln -s /opt/julia-1.10.3/bin/julia /usr/local/bin/julia
289+
tar xzf julia-1.12.4-linux-x86_64.tar.gz
290+
sudo mv julia-1.12.4 /opt/
291+
sudo ln -s /opt/julia-1.12.4/bin/julia /usr/local/bin/julia
368292
```
369293

370294
::::
@@ -866,16 +790,16 @@ not have any CI or code review restrictions. We call this a "feature branch".
866790

867791
The allowed semantic keywords (commit types) are as follows:[^1]
868792

869-
| [Commit type](https://www.conventionalcommits.org/en/v1.0.0/#specification) | [Repository label](https://github.com/organizations/ComPWA/settings/repository-defaults) | Description |
870-
| :-------------------------------------------------------------------------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------- |
871-
| `FEAT` | ![#C2E0C6](https://via.placeholder.com/15/C2E0C6/C2E0C6.png) [✨ Feature](https://github.com/search?o=desc&s=created&type=Issues&q=user%3AComPWA+label%3A%22%E2%9C%A8%20Feature%22) | New feature added to the package |
872-
| `ENH` | ![#C2E0C6](https://via.placeholder.com/15/C2E0C6/C2E0C6.png) [⚙️ Enhancement](https://github.com/search?o=desc&s=created&type=Issues&q=user%3AComPWA+label%3A%22%E2%9A%99%EF%B8%8F%20Enhancement%22) | Improvements and optimizations of existing features |
873-
| `FIX` | ![#e11d21](https://via.placeholder.com/15/e11d21/e11d21.png) [🐛 Bug](https://github.com/search?o=desc&s=created&type=Issues&q=user%3AComPWA+label%3A%22%F0%9F%90%9B+Bug%22) | Bug has been fixed |
874-
| `BREAK` | ![#F9D0C4](https://via.placeholder.com/15/F9D0C4/F9D0C4.png) [⚠️ Interface](https://github.com/search?o=desc&s=created&type=Issues&q=user%3AComPWA+label%3A%22%E2%9A%A0%EF%B8%8F%20Interface%22) | Breaking changes to the API |
875-
| `BEHAVIOR` | ![#F9D0C4](https://via.placeholder.com/15/F9D0C4/F9D0C4.png) [❗ Behavior](https://github.com/search?o=desc&s=created&type=Issues&q=user%3AComPWA+label%3A%22%E2%9D%97%20Behavior%22) | Changes that may affect the framework output |
876-
| `DOC` | ![#bfd4f2](https://via.placeholder.com/15/bfd4f2/bfd4f2.png) [📝 Docs](https://github.com/search?o=desc&s=created&type=Issues&q=user%3AComPWA+label%3A%22%F0%9F%93%9D%20Docs%22) | Improvements or additions to documentation |
877-
| `MAINT` | ![#FFCD8F](https://via.placeholder.com/15/FFCD8F/FFCD8F.png) [🔨 Maintenance](https://github.com/search?o=desc&s=created&type=Issues&q=user%3AComPWA+label%3A%22%F0%9F%94%A8%20Maintenance%22) | Maintenance and upkeep improvements |
878-
| `DX` | ![#FEF2C0](https://via.placeholder.com/15/FEF2C0/FEF2C0.png) [🖱️ DX](https://github.com/search?o=desc&s=created&type=Issues&q=user%3AComPWA+label%3A%22%F0%9F%96%B1%EF%B8%8F%20DX%22) | Improvements to the Developer Experience |
793+
| [Commit type](https://www.conventionalcommits.org/en/v1.0.0/#specification) | Color | [Label](https://github.com/organizations/ComPWA/settings/repository-defaults) | Description |
794+
| :-------------------------------------------------------------------------: | :----------------------------------: | :------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------- |
795+
| `FEAT` | <font color="#C2E0C6">#C2E0C6</font> | [✨&nbsp;Feature](https://github.com/search?o=desc&s=created&type=Issues&q=user%3AComPWA+label%3A%22%E2%9C%A8%20Feature%22) | New feature added to the package |
796+
| `ENH` | <font color="#C2E0C6">#C2E0C6</font> | [⚙️&nbsp;Enhancement](https://github.com/search?o=desc&s=created&type=Issues&q=user%3AComPWA+label%3A%22%E2%9A%99%EF%B8%8F%20Enhancement%22) | Improvements and optimizations of existing features |
797+
| `FIX` | <font color="#E11D21">#E11D21</font> | [🐛&nbsp;Bug](https://github.com/search?o=desc&s=created&type=Issues&q=user%3AComPWA+label%3A%22%F0%9F%90%9B+Bug%22) | Bug has been fixed |
798+
| `BREAK` | <font color="#F9D0C4">#F9D0C4</font> | [⚠️&nbsp;Interface](https://github.com/search?o=desc&s=created&type=Issues&q=user%3AComPWA+label%3A%22%E2%9A%A0%EF%B8%8F%20Interface%22) | Breaking changes to the API |
799+
| `BEHAVIOR` | <font color="#F9D0C4">#F9D0C4</font> | [❗&nbsp;Behavior](https://github.com/search?o=desc&s=created&type=Issues&q=user%3AComPWA+label%3A%22%E2%9D%97%20Behavior%22) | Changes that may affect the framework output |
800+
| `DOC` | <font color="#BFD4F2">#BFD4F2</font> | [📝&nbsp;Docs](https://github.com/search?o=desc&s=created&type=Issues&q=user%3AComPWA+label%3A%22%F0%9F%93%9D%20Docs%22) | Improvements or additions to documentation |
801+
| `MAINT` | <font color="#FFCD8F">#FFCD8F</font> | [🔨&nbsp;Maintenance](https://github.com/search?o=desc&s=created&type=Issues&q=user%3AComPWA+label%3A%22%F0%9F%94%A8%20Maintenance%22) | Maintenance and upkeep improvements |
802+
| `DX` | <font color="#FEF2C0">#FEF2C0</font> | [🖱️&nbsp;DX](https://github.com/search?o=desc&s=created&type=Issues&q=user%3AComPWA+label%3A%22%F0%9F%96%B1%EF%B8%8F%20DX%22) | Improvements to the Developer Experience |
879803

880804
- Keep pull requests small. If the issue you try to address is too big, discuss in the
881805
team whether the issue can be converted into an

‎docs/symbolics.ipynb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -626,7 +626,7 @@
626626
"\n",
627627
"Second, [code generation](#code-generation) makes it possible to serialize symbolic amplitude models to human-readable format for preservation on disk or sharing with others. For example, just as with the generation of numerical functions, the model's [expression tree](#expression-trees) can be used to generate nodes in a serialization format like YAML or JSON. Other analysis frameworks can then import the model for cross-checks or for adapting the analysis to other experiments.\n",
628628
"\n",
629-
"On a technical note, the Python ecosystem in combination with Jupyter Notebooks and [Sphinx](https://www.sphinx-doc.org) (a documentation builder) makes it possible for any reader to directly rerun analysis in the browser or in some local environment. [Pinned dependencies](https://github.com/ComPWA/update-pip-constraints) ensure that the analysis produces the same results."
629+
"On a technical note, the Python ecosystem in combination with Jupyter Notebooks and [Sphinx](https://www.sphinx-doc.org) (a documentation builder) makes it possible for any reader to directly rerun analysis in the browser or in some local environment. {ref}`Pinned dependencies <develop:Pinning dependency versions>` ensure that the analysis produces the same results."
630630
]
631631
},
632632
{

0 commit comments

Comments
 (0)