From 19bbdb467360578c98d9787a9aebca4bf246a8e9 Mon Sep 17 00:00:00 2001 From: Théo Zimmermann Date: Mon, 26 Mar 2018 15:46:33 +0200 Subject: Improve the MERGING doc. In particular, describes what to do with overlays. --- dev/doc/MERGING.md | 34 +++++++++++++++++++++++++++++++--- 1 file changed, 31 insertions(+), 3 deletions(-) (limited to 'dev') diff --git a/dev/doc/MERGING.md b/dev/doc/MERGING.md index 71fc396088..70d8481887 100644 --- a/dev/doc/MERGING.md +++ b/dev/doc/MERGING.md @@ -1,6 +1,7 @@ # Merging changes in Coq -This document describes how patches (submitted as Pull Requests) should be +This document describes how patches (submitted as pull requests +on the `master` branch) should be merged into the main repository (https://github.com/coq/coq). ## Code owners @@ -65,14 +66,41 @@ In some rare cases (e.g. the conflicts are in the CHANGES file), it is ok to fix the conflicts in the merge commit (following the same steps as below), and push to `master` directly. Don't use the GitHub interface to fix these conflicts. -The command to be used is: +To merge the PR proceed in the following way ``` +$ git checkout master +$ git pull $ dev/tools/merge-pr XXXX +$ git push upstream ``` -where `XXXX` is the number of the PR to be merged. This operation should be followed by a push. +where `XXXX` is the number of the PR to be merged and `upstream` is the name +of your remote pointing to `git@github.com:coq/coq.git`. +Note that you are only supposed to merge PRs into `master`. PRs should rarely +target the stable branch, but when it is the case they are the responsibility +of the release manager. + +This script conducts various checks before proceeding to merge. Don't bypass them +without a good reason to, and in that case, write a comment in the PR thread to +explain the reason. Maintainers MUST NOT merge their own patches. DON'T USE the GitHub interface for merging, since it will prevent the automated backport script from operating properly, generates bad commit messages, and a 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)) +and the PR must absolutely update the `CHANGES` file. + +There are two cases to consider: + +- If the patch is backward compatible (best scenario), then you should get + upstream maintainers to integrate it before merging the PR. +- If the patch is not backward compatible (which is often the case when + patching plugins after an update to the Coq API), then you can proceed to + merge the PR and then notify upstream they can merge the patch. This is a + less preferable scenario because it is probably going to create + spurious CI failures for unrelated PRs. -- cgit v1.2.3 From 274da8930804b2187568423c3bfeed541f235001 Mon Sep 17 00:00:00 2001 From: Théo Zimmermann Date: Mon, 26 Mar 2018 15:55:46 +0200 Subject: Some advice about merge script dependencies. Including: how to create a GPG key. --- dev/doc/MERGING.md | 11 +++++++++++ 1 file changed, 11 insertions(+) (limited to 'dev') diff --git a/dev/doc/MERGING.md b/dev/doc/MERGING.md index 70d8481887..402ed37bdc 100644 --- a/dev/doc/MERGING.md +++ b/dev/doc/MERGING.md @@ -104,3 +104,14 @@ There are two cases to consider: merge the PR and then notify upstream they can merge the patch. This is a less preferable scenario because it is probably going to create spurious CI failures for unrelated PRs. + +### Merge script dependencies + +The merge script passes option `-S` to `git merge` to ensure merge commits +are signed. Consequently, it depends on the GnuPG command utility being +installed and a GPG key being available. Here is a short tutorial to +creating your own GPG key: + + +The script depends on a few other utilities. If you are a Nix user, the +simplest way of getting them is to run `nix-shell` first. -- cgit v1.2.3 From 6dd06d92aad8ccd130b4d46b2ff79b71b148bb2b Mon Sep 17 00:00:00 2001 From: Théo Zimmermann Date: Thu, 5 Apr 2018 12:01:24 +0200 Subject: Add note for homebrew users. --- dev/doc/MERGING.md | 5 +++++ 1 file changed, 5 insertions(+) (limited to 'dev') diff --git a/dev/doc/MERGING.md b/dev/doc/MERGING.md index 402ed37bdc..3a2df6a81f 100644 --- a/dev/doc/MERGING.md +++ b/dev/doc/MERGING.md @@ -115,3 +115,8 @@ creating your own GPG key: The script depends on a few other utilities. If you are a Nix user, the simplest way of getting them is to run `nix-shell` first. + +**Note for homebrew (MacOS) users:** it has been reported that installing GnuPG +is not out of the box. Installing explicitly "pinentry-mac" seems important for +typing of passphrase to work correctly (see also this +[Stack Overflow Q-and-A](https://stackoverflow.com/questions/39494631/gpg-failed-to-sign-the-data-fatal-failed-to-write-commit-object-git-2-10-0)). -- cgit v1.2.3