From c0dd7253faa83d1f3230e57071073df321a5e389 Mon Sep 17 00:00:00 2001 From: Théo Zimmermann Date: Tue, 22 May 2018 11:09:58 +0200 Subject: Improve merging and overlay documentations. Clarification prompted by Jim Fehrle. [ci skip] --- dev/ci/user-overlays/README.md | 17 +++++++++++++++-- dev/doc/MERGING.md | 8 +++++--- 2 files changed, 20 insertions(+), 5 deletions(-) (limited to 'dev') 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: -- cgit v1.2.3