git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: "Heba Waly via GitGitGadget" <gitgitgadget@gmail.com>
To: git@vger.kernel.org
Cc: Heba Waly <heba.waly@gmail.com>
Subject: [PATCH v3 0/2] [Outreachy] advice: revamp advise API
Date: Wed, 19 Feb 2020 20:33:59 +0000	[thread overview]
Message-ID: <pull.548.v3.git.1582144442.gitgitgadget@gmail.com> (raw)
In-Reply-To: <pull.548.v2.git.1581889150.gitgitgadget@gmail.com>

Changes in V3:

 * Remove the new wrapper advice_push_update_rejected_enabled() (which was
   added in V2 to handle a special case of having a config variable alias),
   and replace it by adding switch cases to advice_enabled() (The reason
   behind this change is that another special case came up while I was
   migrating the rest of the advise calls to the new APIs.)
 * Remove trailing whitespaces.


----------------------------------------------------------------------------

Main changes in V2:

 * Rename advise_ng to advise_if_enabled.
 * Add a new advise_enabled() helper.
 * Add a list of config variables names to replace advice_config[] (used by
   list_config_advices()).
 * Send an enum parameter to the new advise helpers instead of strings.
 * Extract vadvise() from advise() and advise_if enabled().


----------------------------------------------------------------------------

The advice API is currently a little bit confusing to call. quoting from
[1]:

When introducing a new advice message, you would

 * come up with advice.frotz configuration variable

 * define and declare advice_frotz global variable that defaults to
   true

 * sprinkle calls like this:

  if (advice_frotz)
    advise(_("helpful message about frotz"));

A new approach was suggested in [1] which this patch is based upon.

A new advise_if_enabled() is introduced to gradually replace advise()
advice_enabled() helper is also introduced to be used by those callers who:

 * Only need to check the visibility without calling advise() (they call
   die() or error() instead for example)
 * Need to carry out some heavy processing to display an advice, in this
   case they'll do: if(advice_enabled(advice_type))  advise("some advice message");
   
   

To introduce a new advice message, the caller needs to:

 * Add a new_advice_type to 'enum advice_type'
 * Come up with a new config variable name and add this name to 
   advice_config_keys[]
 * Call advise_if_enabled(new_advice_type, "advice message to be printed")
 * Or call advice_enabled(new_advice_type) first and then follow is by
   advice("advice message to be printed") as explained earlier.
 * Add the new config variable to Documentation/config/advice.txt

The reason a new list of configuration variables was added to the library is
to be used by the list_config_advices() function instead of advice_config[].
And we should get rid of advice_config[] once we migrate all the callers to
use the new APIs instead of checking the global variables (which we'll get
rid of as well).

In the future, we can investigate generating the documentation from the list
of config variables or vice versa to make introducing a new advice much
easier, but this approach will do it for now.

V2 makes the process of introducing a new advice longer than V1 and almost
as long as the original library, but having the advice library responsible
for checking the message visibility is still an improvement and in my own
opinion the new structure makes better sense and makes the library less
confusing to use.

After this patch the plan is to change the advise() calls to
advise_if_enabled() whenever possible, or at least replace the global
variables checks by advise_enabled() when advise_if_enabled() is not
suitable.

[1] https://public-inbox.org/git/xmqqzhf5cw69.fsf@gitster-ct.c.googlers.com/

Heba Waly (2):
  advice: revamp advise API
  advice: extract vadvise() from advise()

 Makefile               |  1 +
 advice.c               | 93 ++++++++++++++++++++++++++++++++++++++----
 advice.h               | 53 +++++++++++++++++++++++-
 builtin/tag.c          |  4 +-
 t/helper/test-advise.c | 16 ++++++++
 t/helper/test-tool.c   |  1 +
 t/helper/test-tool.h   |  1 +
 t/t0018-advice.sh      | 28 +++++++++++++
 t/t7004-tag.sh         |  1 +
 9 files changed, 187 insertions(+), 11 deletions(-)
 create mode 100644 t/helper/test-advise.c
 create mode 100755 t/t0018-advice.sh


base-commit: c7a62075917b3340f908093f63f1161c44ed1475
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-548%2FHebaWaly%2Fadvice_refactoring-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-548/HebaWaly/advice_refactoring-v3
Pull-Request: https://github.com/gitgitgadget/git/pull/548

Range-diff vs v2:

 1:  080d12b5c69 ! 1:  4ab141426f3 advice: refactor advise API
     @@ -1,6 +1,6 @@
      Author: Heba Waly <heba.waly@gmail.com>
      
     -    advice: refactor advise API
     +    advice: revamp advise API
      
          Currently it's very easy for the advice library's callers to miss
          checking the visibility step before printing an advice. Also, it makes
     @@ -63,7 +63,7 @@
      +	[PUSH_UPDATE_REJECTED]			 = "pushUpdateRejected",
      +	/* make this an alias for backward compatibility */
      +	[PUSH_UPDATE_REJECTED_ALIAS]		 = "pushNonFastForward",
     -+	
     ++
      +	[PUSH_NON_FF_CURRENT]			 = "pushNonFFCurrent",
      +	[PUSH_NON_FF_MATCHING]			 = "pushNonFFMatching",
      +	[PUSH_ALREADY_EXISTS]			 = "pushAlreadyExists",
     @@ -99,7 +99,7 @@
       	strbuf_release(&buf);
       }
       
     -+int advice_enabled(enum advice_type type)
     ++static int get_config_value(enum advice_type type)
      +{
      +	int value = 1;
      +	char *key = xstrfmt("%s.%s", "advice", advice_config_keys[type]);
     @@ -107,11 +107,15 @@
      +	return value;
      +}
      +
     -+int advice_push_update_rejected_enabled(void)
     ++int advice_enabled(enum advice_type type)
      +{
     -+	return advice_enabled(PUSH_UPDATE_REJECTED) ||
     -+	       advice_enabled(PUSH_UPDATE_REJECTED_ALIAS);
     -+	
     ++	switch(type) {
     ++	case PUSH_UPDATE_REJECTED:
     ++		return get_config_value(PUSH_UPDATE_REJECTED) &&
     ++		       get_config_value(PUSH_UPDATE_REJECTED_ALIAS);
     ++	default:
     ++		return get_config_value(type);
     ++	}
      +}
      +
      +static const char turn_off_instructions[] =
     @@ -223,12 +227,7 @@
      +int advice_enabled(enum advice_type type);
      +
      +/**
     -+ Checks if PUSH_UPDATE_REJECTED advice type is enabled.
     -+ */
     -+int advice_push_update_rejected_enabled(void);
     -+
     -+/**
     -+ Checks the visibility of the advice before priniting.
     ++ Checks the visibility of the advice before printing.
      + */
      +void advise_if_enabled(enum advice_type type, const char *advice, ...);
      +
     @@ -266,7 +265,7 @@
      +	die("usage: %s <advice>", argv[0]);
      +
      +	setup_git_directory();
     -+	
     ++
      +	//use any advice type for testing
      +	advise_if_enabled(NESTED_TAG, argv[1]);
      +
 2:  3e4f52e5526 ! 2:  a2a145c705e advice: extract vadvise() from advise()
     @@ -38,7 +38,7 @@
       	for (cp = buf.buf; *cp; cp = np) {
       		np = strchrnul(cp, '\n');
      @@
     - 	
     + 	}
       }
       
      -static const char turn_off_instructions[] =

-- 
gitgitgadget

  parent reply	other threads:[~2020-02-19 20:34 UTC|newest]

Thread overview: 76+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-02-10  5:04 [PATCH] advice: refactor advise API Heba Waly via GitGitGadget
2020-02-10 14:38 ` Derrick Stolee
2020-02-10 19:30   ` Junio C Hamano
2020-02-10 19:42     ` Taylor Blau
2020-02-10 22:29       ` Emily Shaffer
2020-02-11  0:08       ` Heba Waly
2020-02-12 20:57         ` Taylor Blau
2020-02-10 23:56   ` Heba Waly
2020-02-11  2:39     ` Derrick Stolee
2020-02-10 20:37 ` Jeff King
2020-02-10 22:55   ` Emily Shaffer
2020-02-11  2:35     ` Heba Waly
2020-02-11 19:49     ` Jeff King
2020-02-11 19:51       ` Jeff King
2020-02-11  2:20   ` Heba Waly
2020-02-10 22:46 ` Junio C Hamano
2020-02-11  2:01   ` Heba Waly
2020-02-11  6:08     ` Junio C Hamano
2020-02-16 21:39 ` [PATCH v2 0/2] [RFC][Outreachy] " Heba Waly via GitGitGadget
2020-02-16 21:39   ` [PATCH v2 1/2] " Heba Waly via GitGitGadget
2020-02-17  3:28     ` Junio C Hamano
2020-02-17 10:03       ` Heba Waly
2020-02-19  9:59     ` Heba Waly
2020-02-16 21:39   ` [PATCH v2 2/2] advice: extract vadvise() from advise() Heba Waly via GitGitGadget
2020-02-17  0:09   ` [PATCH v2 0/2] [RFC][Outreachy] advice: refactor advise API Junio C Hamano
2020-02-19 20:33   ` Heba Waly via GitGitGadget [this message]
2020-02-19 20:34     ` [PATCH v3 1/2] advice: revamp " Heba Waly via GitGitGadget
2020-02-20  1:37       ` Emily Shaffer
2020-02-21  0:31         ` Heba Waly
2020-02-19 20:34     ` [PATCH v3 2/2] advice: extract vadvise() from advise() Heba Waly via GitGitGadget
2020-02-20  1:42       ` Emily Shaffer
2020-02-21  0:34         ` Heba Waly
2020-02-24 15:13     ` [PATCH v4 0/3] [Outreachy] advice: revamp advise API Heba Waly via GitGitGadget
2020-02-24 15:13       ` [PATCH v4 1/3] advice: extract vadvise() from advise() Heba Waly via GitGitGadget
2020-02-24 22:04         ` Emily Shaffer
2020-02-24 15:13       ` [PATCH v4 2/3] advice: revamp advise API Heba Waly via GitGitGadget
2020-02-24 22:05         ` Junio C Hamano
2020-02-24 22:11           ` Eric Sunshine
2020-02-24 23:51             ` Heba Waly
2020-02-24 23:49           ` Heba Waly
2020-02-24 23:45         ` Emily Shaffer
2020-02-24 15:13       ` [PATCH v4 3/3] tag: use new advice API to check visibility Heba Waly via GitGitGadget
2020-02-24 22:07         ` Junio C Hamano
2020-02-24 23:46         ` Emily Shaffer
2020-02-25 10:55       ` [PATCH v5 0/3] [Outreachy] advice: revamp advise API Heba Waly via GitGitGadget
2020-02-25 10:55         ` [PATCH v5 1/3] advice: extract vadvise() from advise() Heba Waly via GitGitGadget
2020-02-25 10:55         ` [PATCH v5 2/3] advice: revamp advise API Heba Waly via GitGitGadget
2020-02-25 17:40           ` Junio C Hamano
2020-02-25 19:56             ` Emily Shaffer
2020-02-25 20:09               ` Junio C Hamano
2020-02-25 20:35                 ` Junio C Hamano
2020-02-25 21:19             ` Heba Waly
2020-02-25 22:02               ` Junio C Hamano
2020-02-26  0:37                 ` Heba Waly
2020-02-26  3:03                   ` Junio C Hamano
2020-02-26 20:28                     ` Heba Waly
2020-02-26 20:44                       ` Junio C Hamano
2020-02-26 21:48                     ` Jonathan Tan
2020-02-25 10:55         ` [PATCH v5 3/3] tag: use new advice API to check visibility Heba Waly via GitGitGadget
2020-02-25 17:48           ` Junio C Hamano
2020-02-27  4:35         ` [PATCH v6 0/4] [Outreachy] advice: revamp advise API Heba Waly via GitGitGadget
2020-02-27  4:35           ` [PATCH v6 1/4] advice: extract vadvise() from advise() Heba Waly via GitGitGadget
2020-02-27  4:35           ` [PATCH v6 2/4] advice: change "setupStreamFailure" to "setUpstreamFailure" Heba Waly via GitGitGadget
2020-02-27 17:38             ` Junio C Hamano
2020-02-27  4:35           ` [PATCH v6 3/4] advice: revamp advise API Heba Waly via GitGitGadget
2020-02-27 20:49             ` Junio C Hamano
2020-02-29  0:58               ` Heba Waly
2020-02-27  4:35           ` [PATCH v6 4/4] tag: use new advice API to check visibility Heba Waly via GitGitGadget
2020-03-02 20:01           ` [PATCH v7 0/4] [Outreachy] advice: revamp advise API Heba Waly via GitGitGadget
2020-03-02 20:01             ` [PATCH v7 1/4] advice: extract vadvise() from advise() Heba Waly via GitGitGadget
2020-03-02 20:01             ` [PATCH v7 2/4] advice: change "setupStreamFailure" to "setUpstreamFailure" Heba Waly via GitGitGadget
2020-03-02 20:01             ` [PATCH v7 3/4] advice: revamp advise API Heba Waly via GitGitGadget
2020-03-02 21:03               ` Junio C Hamano
2020-03-03 14:15                 ` Junio C Hamano
2020-03-04  3:22                   ` Heba Waly
2020-03-02 20:02             ` [PATCH v7 4/4] tag: use new advice API to check visibility Heba Waly via GitGitGadget

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=pull.548.v3.git.1582144442.gitgitgadget@gmail.com \
    --to=gitgitgadget@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=heba.waly@gmail.com \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).