|
| 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