Index API updates for consistency #4807

ethomson · 2018-09-12T18:54:29Z

I've been angry at index.h for a little while now and would like to make some (non-breaking) fixes for better consistency with the project. I'll pile them in here.

pks-t · 2018-09-21T14:05:42Z

include/git2/index.h

@@ -86,7 +86,7 @@ typedef struct git_index_entry {
 typedef enum {
 	GIT_IDXENTRY_EXTENDED  = (0x4000),
 	GIT_IDXENTRY_VALID     = (0x8000),
-} git_indxentry_flag_t;
+} git_idxentry_flag_t;


Huh. This very much does look breaking to me?

Sorry, a bit more constructive: what about also providing a second typedef? typedef git_indxentry_flag_t git_idxentry_flag_t so that nobody needs to change his code?

Maybe, but wouldn't that introduce warnings in user code anyway because of the mismatch ? Thinking about it, I don't think it will, because the usage seems to be limited to bitwise operations. I'm just concerned that a -Werror downstream will have to change the code anyways.

Personally, I'd go for git_index_entry_flag_t for consistency, as that's the name of the struct, and it's part of the index system. I'm fine with just dropping the "n" though, since that's worst 😉.

Sorry, yes, this was very much a WIP that is not at all ready for review. Changing the title to reflect that.

As far as the naming goes, I too would prefer git_index_entry_... except that the rest of the things in this file are named git_idxentry. Possible that we can get away without breakage here, possibly not.

Appreciate the thoughts about -Werror. I'm not sure that we've ever said that we guarantee that people can avoid warnings using libgit2 (and, indeed, you can see that the 32 bit platforms have loads of them that we should deal with but haven't yet). But as that's something to strive for it's something interesting to keep in mind.

ethomson · 2018-11-15T08:35:22Z

Okay, I've updated this to update the names for this prefixed with git_idx_... or git_indx..., moving them to git_index_.... I've also updated the name of git_otype to be git_object_t.

Background: I'm playing around with some automated tools to extract our APIs for a binding and having improved consistency in our naming would be 👍 .

I've added #define old_name new_name to ensure that we don't break consumers. This allows people to continue using their existing code referencing the old names, and to do so without warnings. That is to say, our new APIs will now accept a git_object_t. If we simply keep the old enums around, then compilers will see that old code is sending a git_otype to a git_object_t and warn. Although I don't think we've ever defined "warnings" as a a breaking API change, we can certainly avoid them by simply redefining the old enums to the new ones. eg:

#define GIT_OBJ_COMMIT GIT_OBJECT_COMMIT

so that compilers will see users sending values in the git_object_t enum even though they're using the old names.

While we're here, we can also clean up some unused values that users should not be relying on and in fact represent internal structures that we likely do not want to publish, even if we do start using them internally.

For example, GIT_OBJ__EXT1 should not really be part of the public API. This PR keeps GIT_OBJ__EXT1 for backward compatibility with anybody who is using it, despite its uselessness. (One could imagine another automated tool that has taken it from our API.) However, we do not have a corresponding GIT_OBJECT__EXT1 for the new API.

ethomson · 2018-11-15T08:36:36Z

These first commits change the API definition only. All our own callers are using the old names; I wanted to open this with only those changes to ensure a CI pass with no warnings to address @tiennou's (very reasonable) concerns.

ethomson · 2018-11-15T08:50:37Z

Anyway, I'd love some feedback @tiennou and @pks-t. One question: are you happy with these in a new section in the existing files? Or should they be moved to deprecated.h? I didn't do that but I think I might prefer it.

pks-t

I definitely welcome those changes. I've had my own grief with "git_otype" several times already, because I instinctively searched for "git_object_type" instead. And as you said in another PR, I'm always in favor of having distinctive names instead of saving a few small characters

include/git2/index.h

pks-t · 2018-11-21T12:45:56Z

include/git2/types.h

+	GIT_OBJECT__EXT2 =     5, /**< Reserved. */
+	GIT_OBJECT_OFS_DELTA = 6, /**< A delta, base is given by an offset. */
+	GIT_OBJECT_REF_DELTA = 7, /**< A delta, base is given by object id. */
+} git_object_t;


I'm not sure I like git_object_t. For me, _t usually just says "This is a typedef" instead of "This is a type". So I'd rather vote for either git_object_type or git_object_type_t.

Yeah, I struggled with this one a bit. I agree with you but we're reasonably consistent with _t meaning "this is a type`". A few examples:

git_ref_t

git_branch_t

git_filemode_t

git_cert_t

git_submodule_update_t
...

(It's not perfect, eg git_credtype_t, which does have values of GIT_CREDTYPE_... so that's nice, but they might have been more consistent as GIT_CREDENTIAL_USERNAME...) But anyway, this feels consistent even if it wasn't my preference to begin with.

Fair enough 👍

ethomson · 2018-11-21T22:55:12Z

Thanks - agree with GIT_IDXENTRY_EXTENDED_FLAGS -> GIT_INDEX_ENTRY_EXTENDED_FLAGS and appreciate the formatting issues.

ethomson · 2018-11-22T00:46:57Z

OK, this seems like a change that isn't contentious. I'll update internal callers to use the new names, possible tomorrow (Thanksgiving) but more likely over the weekend.

pks-t

Looks good to me. In the ideal case, we'd add deprecation notices to all those old typedefs. But I'm not sure I'd want to do this immediately, as downstream users are likely to rage in that case as their code will be full of warnings. And I don't even know if it's possible to deprecate macros 🤔

ethomson · 2018-11-28T14:40:31Z

Looks good to me. In the ideal case, we'd add deprecation notices to all those old typedefs. But I'm not sure I'd want to do this immediately, as downstream users are likely to rage in that case as their code will be full of warnings. And I don't even know if it's possible to deprecate macros 🤔

I'm in agreement with you. Let's hold off and do it when we remember which will probably be far enough from now that it seems like a reasonable time to do it. :P

ethomson · 2018-11-29T15:09:33Z

/rebuild

libgit2-azure-pipelines · 2018-11-29T15:09:39Z

Okay, @ethomson, I started to rebuild this pull request as build #1082.

We have various macro, enumeration and structure names that were introduced (very) early in the project and do not match our current naming conventions. For instance: `GIT_IDXENTRY...` flags that correspond to a structure named `git_index_entry`. Update these to match the current guidance. The old macros and enumeration names are reflected as new macros in order to support backward compatibility (and do so without warnings for consumers).

Update the `git_otype` names to reflect our current naming conventions. `git_otype` is now `git_object_t` and the `GIT_OBJ_*` values are now `GIT_OBJECT_*` values. The old macro, enumeration and structure names are retained and simply set to the new names.

The two "reserved" bits in `git_object_t` are unused. They were included for completeness, but downstream users should never use them and they should not have been made public. These values are never set. With the refactoring of `git_otype` into `git_object_t`, we can remove these from the new API. They will remain in the old (deprecated) API in the unlikely event that someone was using them.

git_object_t is the future; update the public API to use it. This will also ensure that we can build our tests which make use of the old API without modification (and without compiler warnings).

Use the new-style index names throughout our own codebase.

Use the new object_type enumeration names within the codebase.

ethomson · 2018-12-01T12:13:16Z

OK, I rebased this. Going to

pks-t reviewed Sep 21, 2018

View reviewed changes

ethomson changed the title ~~index.h: updates for consistency~~ WIP: index.h: updates for consistency Sep 24, 2018

ethomson force-pushed the ethomson/index_fixes branch from 055c067 to f48f38d Compare November 14, 2018 21:14

ethomson changed the title ~~WIP: index.h: updates for consistency~~ WIP: API updates for consistency Nov 14, 2018

ethomson force-pushed the ethomson/index_fixes branch 2 times, most recently from fa78fd0 to 6f1a2f0 Compare November 14, 2018 23:38

pks-t reviewed Nov 21, 2018

View reviewed changes

ethomson force-pushed the ethomson/index_fixes branch from 6f1a2f0 to 3d6e1e3 Compare November 21, 2018 22:54

ethomson force-pushed the ethomson/index_fixes branch from 3d6e1e3 to d3f45a7 Compare November 22, 2018 00:18

ethomson changed the title ~~WIP: API updates for consistency~~ Index API updates for consistency Nov 22, 2018

pks-t approved these changes Nov 28, 2018

View reviewed changes

ethomson force-pushed the ethomson/index_fixes branch from d3f45a7 to ebd55cd Compare November 28, 2018 14:35

ethomson added 5 commits December 1, 2018 10:44

object_type: update public API to use git_object_t

19faf7c

git_object_t is the future; update the public API to use it. This will also ensure that we can build our tests which make use of the old API without modification (and without compiler warnings).

index: use new enum and structure names

18e71e6

Use the new-style index names throughout our own codebase.

ethomson force-pushed the ethomson/index_fixes branch from ebd55cd to 2e8bf25 Compare December 1, 2018 10:48

object_type: use new enumeration names

168fe39

Use the new object_type enumeration names within the codebase.

ethomson force-pushed the ethomson/index_fixes branch from 2e8bf25 to 168fe39 Compare December 1, 2018 11:55

ethomson merged commit 788fccc into master Dec 1, 2018

ethomson mentioned this pull request Dec 27, 2018

Move giterr to git_error #4917

Merged

ethomson deleted the ethomson/index_fixes branch January 9, 2019 10:15

ethomson mentioned this pull request Feb 17, 2019

index.h could use some love #3778

Closed

snyk-bot mentioned this pull request Feb 23, 2020

[Snyk] Upgrade nodegit from 0.4.1 to 0.26.4 saurabharch/Breezeblocks#1

Open

snyk-bot mentioned this pull request Apr 22, 2020

[Snyk] Upgrade nodegit from 0.24.3 to 0.26.5 aminatakonate000/Graviton-App#4

Open

snyk-bot mentioned this pull request May 5, 2020

[Snyk] Upgrade nodegit from 0.24.3 to 0.26.5 Barnstorm-Online/ngp-openapi-generator#1

Open

Index API updates for consistency #4807

Index API updates for consistency #4807

Uh oh!

Conversation

ethomson commented Sep 12, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ethomson commented Nov 15, 2018

Uh oh!

ethomson commented Nov 15, 2018

Uh oh!

ethomson commented Nov 15, 2018

Uh oh!

pks-t left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ethomson commented Nov 21, 2018

Uh oh!

ethomson commented Nov 22, 2018

Uh oh!

pks-t left a comment

Choose a reason for hiding this comment

Uh oh!

ethomson commented Nov 28, 2018

Uh oh!

ethomson commented Nov 29, 2018

Uh oh!

libgit2-azure-pipelines bot commented Nov 29, 2018

Uh oh!

ethomson commented Dec 1, 2018

Uh oh!

Uh oh!