aboutsummaryrefslogtreecommitdiffhomepage
diff options
context:
space:
mode:
authorGravatar Théo Zimmermann <theo.zimmermann@univ-paris-diderot.fr>2018-05-22 11:09:58 +0200
committerGravatar Théo Zimmermann <theo.zimmermann@univ-paris-diderot.fr>2018-05-24 16:44:40 +0200
commitc0dd7253faa83d1f3230e57071073df321a5e389 (patch)
treee5406500c63a7087ed8de023e293814edbd74528
parente43b85c925c0c9c87e1dde69760d9ea343c5cfa8 (diff)
Improve merging and overlay documentations.
Clarification prompted by Jim Fehrle. [ci skip]
-rw-r--r--dev/ci/user-overlays/README.md17
-rw-r--r--dev/doc/MERGING.md8
2 files changed, 20 insertions, 5 deletions
diff --git a/dev/ci/user-overlays/README.md b/dev/ci/user-overlays/README.md
index a7474e324..3414a8786 100644
--- a/dev/ci/user-overlays/README.md
+++ b/dev/ci/user-overlays/README.md
@@ -1,8 +1,21 @@
# Add overlays for your pull requests in this directory
-An overlay is a file containing very simple logic to test whether we are currently building a specific pull request or git branch (useful so that overlays work on your own fork) and which changes some of the variables whose default can be found in [`ci-basic-overlay.sh`](/dev/ci/ci-basic-overlay.sh).
+When your pull request breaks an external development we test in our CI, you
+must prepare a patch (or ask someone to prepare a patch) to fix this development.
+Backward compatible patches are to be preferred, especially on libraries (it is
+harder to make backward compatible patches for plugins).
-The name of your overlay file should be of the form `five_digit_PR_number-GitHub_handle-branch_name.sh`.
+Once you have a patched version, you can add an overlay to your pull request:
+this is a file which defines where to look for the patched version so that
+testing is possible. It changes the value of some variables from
+[`ci-basic-overlay.sh`](/dev/ci/ci-basic-overlay.sh) (generally both the
+`_CI_BRANCH` and the `_CI_GITURL` variables of a given development at once).
+
+The file contains very simple logic to test the pull request number or branch
+name and apply it only in this case.
+
+The name of your overlay file should be of the form
+`five_digit_PR_number-GitHub_handle-branch_name.sh`.
Example: `00669-maximedenes-ssr-merge.sh` containing
diff --git a/dev/doc/MERGING.md b/dev/doc/MERGING.md
index a466124c1..14d30517c 100644
--- a/dev/doc/MERGING.md
+++ b/dev/doc/MERGING.md
@@ -43,8 +43,8 @@ A maintainer is expected to be reasonably reactive, but no specific timeframe is
given for reviewing.
(*) In case a component is touched in a trivial way (adding/removing one file in
-a `Makefile`, etc), or by applying a systematic process (global renaming,
-deprecationg propagation, etc) that has been reviewed globally, the assignee can
+a `Makefile`, etc), or by applying a systematic refactoring process (global
+renaming for instance) that has been reviewed globally, the assignee can
say in a comment they think a review is not required and proceed with the merge.
## Merging
@@ -92,7 +92,9 @@ messy history when there are conflicts.
### What to do if the PR has overlays
If the PR breaks compatibility of some developments in CI, then the author must
-have prepared overlays for these developments (see [`dev/ci/README.md`](/dev/ci/README.md))
+have prepared overlays for these developments (see
+[`dev/ci/user-overlays/README.md`](/dev/ci/user-overlays/README.md) for
+detailed explanations of what this is)
and the PR must absolutely update the `CHANGES` file.
There are two cases to consider: