On 12/16/2015 20:22, Mike Holmes wrote:
On 16 December 2015 at 05:50, Maxim Uvarov <maxim.uva...@linaro.org
<mailto:maxim.uva...@linaro.org>> wrote:
On 12/15/2015 21:06, Mike Holmes wrote:
Describe how changes to the public api are handled from
release to release.
Signed-off-by: Mike Holmes <mike.hol...@linaro.org
<mailto:mike.hol...@linaro.org>>
---
doc/process-guide/release-guide.adoc | 38
++++++++++++++++++++++++++++++++++++
1 file changed, 38 insertions(+)
diff --git a/doc/process-guide/release-guide.adoc
b/doc/process-guide/release-guide.adoc
index f5d29d2..d932118 100644
--- a/doc/process-guide/release-guide.adoc
+++ b/doc/process-guide/release-guide.adoc
@@ -134,3 +134,41 @@ made every month if sufficient change has
accumulated.
=== Implementation (Impl) ===
Platform specific free form text relating to the version.
+
+== Deprecated APIs
+
+Whenever an API is changed as part of an api-next patch the
following rules
+apply to provide a warning to implementers and users.
+
+* A patch will be applied to api-next that adds the
deprecated indication to
+the old public API in odp/include
That sentence should never be in product documentation. Plans can
be in
Jira cards, bugs, mailing list, but published docs should relay
only on work
which is already done.
I dont follow the rationale that this is the wrong place, this is the
document that does describe how we will operate, we dont specify which
patch just how they will be used.
Sorry, for first read I thought that want to send patch to api-next to
mark functions as deprecated. Instead of current one. But you
just defining list of rules for such deprecated patch. It's a little bit
confusing senescence for me as non native English.
Might be:
1. add ":" after "users". So reader can expect some list.
2. Rephrase sentence to: "Patch which marks existence api (odp/include)
with deprecated indication should be applied on api-next first. Same way
as all other api changes patches."
(if we name it "rules", not "plans" - it has to be not future form,
right? I.e. have to, must).
+* A patch will be applied to api-next that adds the new API
and removes the
+old, in these cases the implementation and tests must also
change at the same
+time to ensure that CI shows no regressions in the api-next
branch.
same here.
describing how we operate is the purpose of this doc
That also I understood wrongly.
But replace old by new is not deprecation. It's just api replacement.
That should be in api-next branch
description. And chapter Deprecated APIs should have rules only suitable
for deprecation.
+* When the Release Manager has scheduled the api change to be
released in a
+future version, the initial deprecated patch will be moved to
next branch and
+released in the next release cycle.
+* When at a minim of one release cycle has passed, and
possibly longer as
+specified by the Release Manager the complete change will be
merged to next and
+then released in the next cycle.
Release Manager scheduled in next release cycle ... It's it too
complex
to read and understand when and what will be done. How about be more
community friendly in sentences? Something like:
We can certainly try to make it clearer and put the points on a
diagram to show how they relate in time.
My point is - it's easy to mark function as deprecated. But you never
know what time will take transition period
that everybody will stop using it. Linux kernel has some deprecated
function which warn for years. And I think
that right thing will be discussion before next big release if we want
to remove some specific functions.
""
ODP API provides special API to mark function and data types as
deprecated.
This is not true, there is no API only a doxygen comment.
everything what is in ./include/odp/api we consider as API, right?
include/odp/api/hints.h
#define ODP_DEPRECATED __attribute__((__deprecated__))
Marking function as deprecated means that ODP Community will
support all
functionality for that function, validation tests and test
execution in CI system.
No, deprecated means literally that you should stop using something.
In our case becasue it will change and you can view the new version in
api-next.
It depends from with point of view you are looking. Yes it says - stop
using it. But that api should still have implementation and validation tests
for linux-generic. I.e. we have to support it for some time until it's
completely removed.
Because of support of both new API and deprecated adds additional
load and
increase complexity marking functions as deprecated will happen
only for
specific reason.
We will mark them deprecated when the current API can be shown to be
deficient and a better alternative has already been proven in api-next.
yes, it was just sentence to document. That there should be specific reason.
That reason should be valuable, discussed in ODP community meetings,
recorded in mailing list and corresponding bug entry should be open.
Yes, that is why we created api-next so that the community can
comment and give feedback
also just sentence to your process doc - where exactly we store that
specific reason.
Also some transition
period for supporting old API should be defined.
The release manager role is the one that ensures that all the process
has been completed and schedules the change to actually occur, at no
point will the old api be supported concurrently unless it is in a
long term support version. The period for which the deprecated element
is flagged will vary and will generally be reached by consensus in
api-next discussion.
It does not matter who will control that process. Idea is that document
should say where it will be documented. I.e. each developer
can go to bug entry find information that for example function x() is
deprecated in odp1.5 and will be removed in odp2.0, use y().
Might be doxygen can have all information about time.
btw, can we in doxygen have list of all things marked as @deprecated?
That list will be very easy to review.
+
+NOTE: Any given release never supports two versions of an API
+
That is not what deprecated means. I.e. deprecated means
absolutely opposite - support old version
and new at the same time.
No, "*Deprecation* is an attribute applied to a computer software
<https://en.wikipedia.org/wiki/Computer_software> feature,
characteristic, or practice to indicate that it should be avoided
(often because it is being superseded). "
It says nothing about supporting it in parallel with a new variant.
ODP support during this period comes in the form that the old api
will still work while the warning is in effect that you should plan on
stopping using it. You don't have to stop using it, you could remain
on that release.
Yes. Again, from which side are you looking from odp apps developer or
from odp developer. Both api have to work. That means they should
pass and have validation tests, correct implementation and etc.
+.Marking a deprecated API element
+[source,c]
+----
+/**
+ * Get buffer handle from event
+ *
+ * Converts an ODP_EVENT_BUFFER type event to a buffer.
+ *
+ * @deprecated This api will be removed for some good reason
defined here
doxygen is not enough I think. Also here might be some short
description and link to bug.
+odp_buffer_t odp_buffer_from_event(odp_event_t ev) ODP_DEPRECATED;
and compile with: -Wno-deprecated-declarations
Maxim.
+ *
+ * @param ev Event handle
+ *
+ * @return Buffer handle
+ *
+ * @see odp_event_type()
+ */
+odp_buffer_t odp_buffer_from_event(odp_event_t ev);
+----
\ No newline at end of file
_______________________________________________
lng-odp mailing list
lng-odp@lists.linaro.org <mailto:lng-odp@lists.linaro.org>
https://lists.linaro.org/mailman/listinfo/lng-odp
--
Mike Holmes
Technical Manager - Linaro Networking Group
Linaro.org <http://www.linaro.org/>***│ *Open source software for ARM SoCs
_______________________________________________
lng-odp mailing list
lng-odp@lists.linaro.org
https://lists.linaro.org/mailman/listinfo/lng-odp
