net/gcoap: deprecate gcoap_finish() #12838
Conversation
kb2ma
added
Type: cleanup
sys/include/net/gcoap.h
Outdated
| @@ -739,6 +748,9 @@ int gcoap_req_init(coap_pkt_t *pdu, uint8_t *buf, size_t len, | |||
| * Assumes the PDU has been initialized with a gcoap_xxx_init() function, like | |||
| * gcoap_req_init(). | |||
| * | |||
| * @deprecated Will be removed after the 2020.04 release. Use | |||
There was a problem hiding this comment.
Don't we usually remove after two cycles? We are in the middle of the 2020.01 release cycle, so the proper removal release would be 2020.07.
There was a problem hiding this comment.
Yes, that's what I was trying to say. When I read, "after the 2020.04 release", that implies sometime before 2020.07 is released. I adopted this expression from other deprecations I had seen. Perhaps I misunderstood.
IMO it would be clearer to say "Will be removed for the 2020.07 release." What do you think?
There was a problem hiding this comment.
IMO it would be clearer to say "Will be removed for the 2020.07 release." What do you think?
Yes, that is typically what we mean with "after two cycles": Starting from the current one under development + 2 releases. The "after" refers to the fact that it will be removed during the release development and thus not be available after the release is out.
There was a problem hiding this comment.
Just to be clear, I hear you say that you prefer:
Will be removed after the 2020.07 release.
rather than
Will be removed for the 2020.07 release.
To me "removed" is an active verb that means "the act of taking it out". So, it sounds like you are saying the act of taking out the function will happen after the release.
[edit -- scratch the text below; "after" just doesn't make sense to me in this context]
So, to keep the word "after" it would be clearer to use what you stated in your comment:
Will be unavailable after the 2020.07 release.
There was a problem hiding this comment.
You are the native speaker ^^" and what you say makes sense to me. Then let's go for "unavailable" or "not available [edit: anymore]" (the latter I prefer somehow, can't really explain why, though semantically they have the same meaning).
|
Comments addressed. |
|
ping @miri64 ! |
miri64
added
the
CI: ready for build
|
@kb2ma please squash! |
kb2ma
force-pushed
the
gcoap/deprecate_gcoap_finish
branch
from
04bcf81
to
57cd900
Compare
|
Squashed and Travis happy. |
|
Murdock as well. |
Contribution description
gcoap's implementation has been transitioning to use a common API with nanocoap to build a message:
gcoap_finish()from gcoap's original API withcoap_opt_finish()This PR deprecates gcoap_finish(), with removal scheduled for after the 2020.04 release. This PR also deprecates the three GCOAP_xxx_OPTIONS_BUF macros, which are used only to accommodate gcoap_finish().
Also, somehow a use of gcoap_finish() has crept into the code in cord_epsim. I plan to create a separate PR to replace that use.
Testing procedure
Build the documentation and ensure deprecation notices appear for the function and the macros.
Issues/PRs references
See above.