Deprecate functions and constants more gently #4952
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
ethomson
force-pushed
the
ethomson/deprecation
branch
5 times, most recently
from
85bfd71
to
ce2f006
Compare
|
OK, here's a proposal for a "softer" deprecation; instead of marking things as deprecated with an attribute, we simply stuff them into their own file. The exception being This introduces |
ethomson
referenced
this pull request
Jan 24, 2019
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, by changing the type signatures to `git_object_t` and declaring the old `GIT_OBJ_` values as a signed or unsigned int, we risk a mismatch between what the compiler has chosen for a `git_object_t`'s type and our type declaration. Thus, we declare the deprecated values as the enum instead of guessing.
pks-t
approved these changes
Jan 24, 2019
src/common.h
Outdated
| @@ -76,6 +76,7 @@ | |||
|
|
|||
| #include "git2/types.h" | |||
| #include "git2/errors.h" | |||
| #include "git2/deprecated.h" | |||
There was a problem hiding this comment.
This include shouldn't be necessary in the end, right? None of our internal code is supposed to use deprecated functions or constants. With the exception of test code, I guess
ethomson
force-pushed
the
ethomson/deprecation
branch
2 times, most recently
from
a1dfa48
to
972d1dd
Compare
`git_stream_register_tls` is now deprecated; mark it in an if guard with the deprecation. This should not be included in `deprecated.h` since it is an uncommonly used `sys` header file.
Add `@deprecated` to the functions that are, so that they'll appear that way in docurium.
Avoid the deprecated `git_stream_cb` typedef since we want to compile the library without deprecated functions or types. Instead, we can unroll the alias to its actual type.
Move the deprecated stream tests into their own compilation unit. This will allow us to disable any preprocessor directives that apply to deprecation just for these tests (eg, disabling `GIT_DEPRECATED_HARD`).
Users can define `GIT_DEPRECATE_HARD` if they want to remove all functions that we've "softly" deprecated.
Ensure that we do not use any deprecated functions in the library source, test code or examples.
ethomson
force-pushed
the
ethomson/deprecation
branch
from
972d1dd
to
c951b82
Compare
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Provide a new kindler, gentler deprecation policy for the upcoming release.
deprecated.h.GIT_DEPRECATEDattribute from the deprecated bits. This will allow users to more gently move into the new functions at their leisure. We have no hurry in removing the old functions or values, so let's not rush things.GIT_DEPRECATE_HARDto completely remove the deprecated functions.GIT_DEPRECATE_HARDourselves to ensure that we don't use them in the library code, tests, or examples.I've kept the
GIT_DEPRECATEDmacro so that we can mark something as properly deprecated, using the compiler attributes, in the future if we desire.