Skip to content

Commit 30cb9d6

Browse files
authored
Merge pull request #198 from booxter/ci-deps-constraints
Document pip constraints CI enforcement for all dependencies
2 parents 6a660e7 + a7e6ce4 commit 30cb9d6

File tree

3 files changed

+68
-1
lines changed

3 files changed

+68
-1
lines changed

.spellcheck-en-custom.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,7 @@ Langgraph
120120
leaderboard
121121
lifecycle
122122
lignment
123+
linters
123124
LLM
124125
LLMs
125126
llms

docs/ci/dependency-constraints.md

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Dependency Constraints in InstructLab CI
2+
3+
This document describes how Python dependencies should be managed in
4+
InstructLab CI.
5+
6+
## Goals
7+
8+
1. Ensure that the CI environment is consistent and reproducible.
9+
2. Ensure that new dependency releases do not break the CI environment.
10+
3. Ensure that we adopt new dependency releases in the CI environment in a
11+
timely manner.
12+
13+
## Approach
14+
15+
### Pin all versions with constraints files
16+
17+
Each repository should contain a [pip
18+
constraints](https://pip.pypa.io/en/stable/user_guide/#constraints-files) file
19+
that lists the pinned versions of all dependencies used in the CI environment.
20+
21+
In case a repository supports multiple platforms (`linux` vs `darwin`) or
22+
accelerators (`cuda`, `cpu`, `hpu`), multiple constraints files may be
23+
generated.
24+
25+
The constraints files should be used in all CI jobs that install Python
26+
dependencies (using `pip` or otherwise), including linters, unit tests,
27+
integration tests, and functional tests.
28+
29+
### Update constraints files regularly
30+
31+
Each repository should define a new `tox` target called `constraints` that will
32+
be used to re-generate all the constraints files in the project.
33+
34+
Updates to these files should be generated automatically by the CI system using
35+
the [update-constraints](https://github.com/instructlab/ci-actions/tree/main/actions/update-constraints)
36+
action from `ci-actions` repository and should not be modified manually
37+
(subject to rare exceptions). A periodic CI job should be added to ensure this
38+
happens on a regular basis (at least once a week).
39+
40+
The job will update constraints file and post the result as a PR for review.
41+
The PR will be validated by all the relevant CI jobs. Project core team is
42+
expected to review these PRs in a timely manner (within 3 business days). The
43+
team should make sure that all the relevant CI jobs are passing before merging
44+
the PR.
45+
46+
### Uncap all dependencies
47+
48+
At this point, no new dependency releases should affect the CI environment.
49+
Projects should then uncap all their dependencies in requirements files, as per
50+
[dependency management policy](../dependency-management.md).
51+
52+
Note: In rare situations, a cap may be justified. For example, when we know for
53+
sure that a new release of the upstream dependency will break the project, and
54+
when we don't have capacity to deliver a fix in a timely manner. These
55+
situations should be rare and a mitigation plan should be in place to uncap the
56+
dependency.
57+
58+
Specifically,
59+
60+
- A tracking issue should be reported in the issue tracking system capturing
61+
any known details about the issue.
62+
- A new **temporary** constraint should be added to `constraints-dev.txt.in`
63+
file. The temporary constraint should refer to the tracking issue in a
64+
comment above it.
65+
- The tracking issue should be assigned a high priority and considered a
66+
blocker for an upcoming release.

docs/dependency-management.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ This document describes the policies for adding and updating build and runtime d
1111
4. Only apply "caps" to dependencies (using `<`) when that dependency has established a pattern of producing new releases with breaking changes.
1212
5. Pin versions in CI, with frequent automated updates.
1313

14-
Best practices for python dependencies call for using ranges in package requirements and pinning versions only in CI jobs.
14+
Best practices for python dependencies call for using ranges in package requirements and [pinning versions only in CI jobs](./ci/dependency-constraints.md).
1515

1616
Using pinned versions in a list of constraints used for tests allows us to know and advertise exactly what versions have been tested in CI.
1717
That information is useful for users and re-packagers to understand which versions of dependencies are compatible with more specificity than the ranges provide.

0 commit comments

Comments
 (0)