Improve deprecation of old enums

[ethomson]

Add __attribute__((used)) to the GIT_DEPRECATED macro, otherwise this will be seen as an "unused const variable".

Also, use the enum type in the declaration of deprecated values. The C standard does not specify whether an enum is a signed or unsigned type. Obviously, any enum that includes negative values must be signed, but if all values are positive then the compiler is free to choose signed or unsigned.
Thus, we declare the deprecated values as the enum instead of guessing.

[ethomson]

Note that I'm still a little bit on the fence about how we're deprecating these; I think that it might make sense to just keep them as #defines or what not until 1.0 ships, then mark them as deprecated. I don't think we need to be in any hurry to get rid of them. But I want more input on that.

[pks-t]

Yeah, I think keeping them as #defines instead of using static variables would be preferable. No increase in binary size, no problems with symbols being unused and it looks cleaner. Is it possible to deprecate macros though?

I don't think it's going to matter when we deprecate things: at some point in time, users will most likely be annoyed by the warnings. I'm rather pessimistic that anybody will actually update his code as long as they are not explicitly being marked as deprecated to emit warnings. Not saying this is due to lazyness, but more due to discoverability. I wouldn't think that every downstream user reads our release notes.

[ethomson]

Is it possible to deprecate macros though?

AFAICT, no, it's not. Certainly not on all compilers, but maybe you could do some epic hackery to do something.

I'm rather pessimistic that anybody will actually update his code as long as they are not explicitly being marked as deprecated to emit warnings.

I agree. My counterpoint, though, is, do we ever really need to remove these for anything other than our own clutter? We could create deprecated.h, dump all these things in there, and forget about them forever.

This has the advantage of us being able to use #defines instead of static const int, keeping the size down and simplicity.

[ethomson]

What I mentioned up there (the #define for now, mark them deprecated after 1.0) is a middle of the road approach that I'm not sure I really care about.

[pks-t]

I'm fine with a deprecated.h header. As you said in another thread, we should include it by default in "libgit2.h" as long as nothing like e.g. LIBGIT2_NO_DEPRECATED is defined.

[tiennou]

Are static const int counted as binary ? I was under the impression that, given const, they would be optimized to their integer representation anyway, but I could be wrong. This, plus the missing support for macros (I think clang was the culprit at the time) is why I favored not using a #define.

My POV is that, it depends on the amount of fixing needed by the deprecation. Things like git_buf_free/dispose are pretty mechanical changes, and I'd feel better to have them removed before 1.0.

[ethomson]

My question is: why remove them at all?

[pks-t]

On Mon, Jan 21, 2019 at 07:49:16AM -0800, Edward Thomson wrote: My question is: why remove them at all?

I'd always vote to remove deprecated things that are expected to be a maintenance burden in the long run. But all the deprecations we have done now (git_buf_free, git_objtype, giterr) are quite trivial and I don't expect us to touch them again in the near- or mid-term future. As long as we move away the old declarations to decrease their visibility like @ethomson proposed with the "deprecated.h" header, I would be fine with keeping them for a long time.