Skip to content

Commit 6832ad4

Browse files
Copilotpancetta
Copilot
and
pancetta
committed
Add dependency management quick reference and update README
- Create quick reference guide for common dependency tasks - Add dependency management section to main README - Link to all dependency documentation - Complete documentation suite for automated dependency management Co-authored-by: pancetta <7158893+pancetta@users.noreply.github.com>
1 parent 3084a36 commit 6832ad4

File tree

2 files changed

+132
-0
lines changed

2 files changed

+132
-0
lines changed

‎DEPENDENCY_QUICKREF.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Quick Reference: Dependency Management
2+
3+
## For Users
4+
5+
**Installing pySDC:**
6+
```bash
7+
# Using pip (gets core dependencies)
8+
pip install pySDC
9+
10+
# Using conda with environment file (recommended for development)
11+
git clone https://github.com/Parallel-in-Time/pySDC.git
12+
cd pySDC
13+
micromamba env create -f etc/environment-base.yml
14+
micromamba activate pySDC
15+
pip install --no-deps -e .
16+
```
17+
18+
**Using lock files for exact reproducibility:**
19+
```bash
20+
# If lock files are available (coming soon)
21+
micromamba install -f etc/lockfiles/environment-base-lock.yml
22+
```
23+
24+
## For Contributors
25+
26+
**Adding dependencies to your project:**
27+
1. Edit `pySDC/projects/YOUR_PROJECT/environment.yml`
28+
2. Use format: `package>=min_version,<max_major_version`
29+
3. Example: `numpy>=1.20.0,<3.0`
30+
31+
See: [Adding a Project Guide](docs/contrib/06_new_project.md)
32+
33+
**Updating dependencies:**
34+
- Lock files update automatically weekly (Sundays)
35+
- You don't need to manually update version constraints
36+
- Just specify what you need with reasonable bounds
37+
38+
## For Maintainers
39+
40+
**When lock file PR is created (Sundays):**
41+
1. Review the PR created by the automated workflow
42+
2. Check CI results
43+
3. If tests pass: Merge
44+
4. If tests fail: Investigate, may need to tighten constraints
45+
46+
**When Monday CI fails:**
47+
1. Check if a lock file update PR exists
48+
2. Review automated failure analysis PR
49+
3. Identify problematic dependency
50+
4. Options:
51+
- Merge lock file PR if it fixes the issue
52+
- Add tighter upper bound in source file
53+
- Update code for new dependency version
54+
55+
**Manual lock file update:**
56+
```bash
57+
# Update all lock files
58+
./etc/scripts/update_all_lockfiles.sh
59+
60+
# Update specific environment
61+
./etc/scripts/update_lockfile.sh etc/environment-base.yml
62+
```
63+
64+
**Adding upper bound to dependency:**
65+
1. Edit the relevant environment.yml or pyproject.toml
66+
2. Change `package>=X.Y` to `package>=X.Y,<Z.0`
67+
3. Regenerate lock files: `./etc/scripts/update_all_lockfiles.sh`
68+
4. Commit changes
69+
70+
## Common Tasks
71+
72+
### I want reproducible builds
73+
**Use lock files** (when available):
74+
```bash
75+
micromamba install -f etc/lockfiles/environment-base-lock.yml
76+
```
77+
78+
### I want the latest versions
79+
**Use source files**:
80+
```bash
81+
micromamba env create -f etc/environment-base.yml
82+
```
83+
84+
### I need to pin a specific version
85+
**Edit the environment.yml**:
86+
```yaml
87+
dependencies:
88+
- package==X.Y.Z # Exact version
89+
```
90+
Then update lock files.
91+
92+
### A dependency broke my code
93+
**Add upper bound**:
94+
```yaml
95+
dependencies:
96+
- package>=X.Y,<X.Z # Block the breaking version
97+
```
98+
Then update lock files and open issue to fix code.
99+
100+
## Key Files
101+
102+
| File | Purpose |
103+
|------|---------|
104+
| `pyproject.toml` | Core pip dependencies |
105+
| `etc/environment-*.yml` | Base environments for different configs |
106+
| `pySDC/projects/*/environment.yml` | Project-specific dependencies |
107+
| `etc/lockfiles/*-lock.yml` | Exact versions (auto-generated) |
108+
| `.github/workflows/update_lockfiles.yml` | Automated lock file updates |
109+
110+
## Documentation
111+
112+
- **[Complete Guide](docs/contrib/08_dependency_management.md)** - Full dependency management documentation
113+
- **[Lock File System](etc/README.md)** - Lock file implementation details
114+
- **[Timeline](DEPENDENCY_TIMELINE.md)** - Weekly workflow visualization
115+
- **[Solution Summary](DEPENDENCY_SOLUTION.md)** - Overview of the solution
116+
117+
## Weekly Schedule
118+
119+
- **Sunday 2:00 AM UTC**: Lock files update automatically
120+
- **Monday 5:01 AM UTC**: Weekly CI run
121+
122+
This ensures lock files are tested before the weekly CI run.
123+
124+
## Need Help?
125+
126+
1. Check [Dependency Management Guide](docs/contrib/08_dependency_management.md)
127+
2. Review [Troubleshooting section](docs/contrib/08_dependency_management.md#troubleshooting)
128+
3. Check automated failure PR (if Monday CI failed)
129+
4. Check lock file update PR (if available)
130+
5. Open an issue with details

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,8 @@ decent installation of this is needed in order to run those examples.
8383
When using `fenics` or `petsc4py`, a C++
8484
compiler is required (although installation may go through at first).
8585

86+
**Dependency Management:** pySDC uses automated dependency management with lock files and upper bounds. See the [Dependency Quick Reference](./DEPENDENCY_QUICKREF.md) for common tasks, or the [complete dependency management guide](./docs/contrib/08_dependency_management.md) for details.
87+
8688
For more details on `pySDC`, check out http://www.parallel-in-time.org/pySDC.
8789

8890
## How to cite

0 commit comments

Comments
 (0)