Skip to content

Commit fafd871

Browse files
committed
docs(ct): add README for backports directory and usage guidelines
Introduced documentation detailing the structure, purpose, and usage of the `src/backports` directory to support consistent patch management across multiple Dataverse release versions.
1 parent 388c55f commit fafd871

File tree

1 file changed

+81
-0
lines changed

1 file changed

+81
-0
lines changed

src/backports/README.md

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Backports Directory
2+
3+
This directory contains patch files for backporting changes across different Dataverse releases.
4+
These changes can be features, build enhancements, security patches, and more.
5+
6+
## Directory Structure
7+
8+
The backports directory is organized by "release version" (or "release tag") folders.
9+
Each folder name corresponds to a [Dataverse release](https://github.com/IQSS/dataverse/releases) and [its associated Git tag](https://github.com/IQSS/dataverse/tags):
10+
11+
```
12+
src/backports/
13+
├── v6.4/ # Patches for Dataverse 6.4
14+
├── v6.5/ # Patches for Dataverse 6.5
15+
├── v6.6/ # Patches for Dataverse 6.6
16+
└── ...
17+
```
18+
19+
Each version folder contains numbered patch files that modify specific components.
20+
21+
For example:
22+
- `001-parent-pom.xml.patch` -> Modifications to the parent POM configuration
23+
- `002-pom.xml.patch` -> Changes to the main POM file
24+
- Additional patches as needed.
25+
26+
## Intended Usage
27+
28+
The patch files in each release folder are designed to be applied in numerical order.
29+
30+
Currently, they are primarily used by the container maintenance workflows (see `.github/workflows/container_maintenance.yml`) to ensure maintenance script compatibility across different Dataverse versions.
31+
See also the "three releases back" support promise at https://guides.dataverse.org/en/latest/container/app-image.html#tags-for-production-use.
32+
33+
*Note: The backport patches mechanism is by no means limited to usage in a container context.*
34+
*They can be applied manually or from some other automated release process to backports changes to older releases.*
35+
36+
## Creating Patch Files
37+
38+
To create a new patch file using `git diff`, follow these steps:
39+
40+
### Example: Creating a POM patch
41+
42+
1. **Make your changes** to the target file(s) on the appropriate branch (usually your feature branch).
43+
2. **Head to the root** of the Git repository.
44+
3. **Generate the patch** using `git diff`:
45+
```bash
46+
# Create a patch for changes to pom.xml, comparing with the pom.xml contained in the v6.5 tag:
47+
git --no-pager diff v6.5 pom.xml > src/backports/v6.5/002-pom.xml.patch
48+
49+
# Or create a patch for multiple files:
50+
git --no-pager diff v6.5 modules/dataverse-parent/pom.xml pom.xml > src/backports/v6.5/003-multi-pom.patch
51+
52+
# Create a patch from staged changes
53+
git diff --cached > src/backports/v6.5/004-staged-changes.patch
54+
```
55+
56+
4. **Review the patch** to ensure it contains only the intended changes:
57+
```bash
58+
cat src/backports/v6.5/002-pom.xml.patch
59+
```
60+
61+
5. **Repeat for other tags** as necessary.
62+
63+
### Patch Naming Convention
64+
65+
Use the following naming pattern:
66+
- `001-` prefix with three-digit numbering for ordering
67+
- Descriptive name indicating what is being patched
68+
- `.patch` file extension
69+
70+
Examples:
71+
- `001-parent-pom.xml.patch`
72+
- `002-pom.xml.patch`
73+
- `003-dockerfile-updates.patch`
74+
75+
## Integration with CI/CD
76+
77+
These patches are automatically applied during the container maintenance workflows to ensure that older release versions can be built with updated dependencies and configurations while maintaining compatibility.
78+
The patches support the multi-version container image strategy that builds and maintains Docker images for the current development branch plus the last three released versions.
79+
See also the "three releases back" support promise at https://guides.dataverse.org/en/latest/container/app-image.html#tags-for-production-use.
80+
81+
In the future, other automations may pick up the patches to release updated WAR files or similar.

0 commit comments

Comments
 (0)