mesos-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Neil Conway <neil.con...@gmail.com>
Subject Re: Tracking deprecated features
Date Tue, 07 Feb 2017 16:33:15 GMT
Strongly agree that this can and should be improved! Two questions/suggestions:

(1) Should we use JIRA, the website/docs, or both? If we only use
JIRA, it might not be obvious to users that, e.g., the "--roles"
master flag is deprecated. An alternative would be a table in the
docs, listing (a) when a feature was deprecated, (b) when a feature
will be removed, (c) links to JIRAs.

(2) In some ways, experimental features are the inverse of deprecated
features (e.g., typical evolution might be experimental -> stable ->
deprecated -> removed). We should make it more clear to users (a)
which features are currently experimental, and (b) when those
experimental features graduate to being "stable". I wonder if we could
use a similar system to what you propose for making this information
more clear to users.

Neil

One thing I wonder about is whether we should use the website/docs,
JIRA, or both
On Tue, Feb 7, 2017 at 2:56 AM, Benjamin Bannier
<benjamin.bannier@mesosphere.io> wrote:
> Hi,
>
> we currently track deprecation of features largely through TODOs in the source code.
Here we typically write down a release at which a deprecated feature should be removed.
>
> I believe this is less than optimal since
>
> * it is hard for users of our APIs to track when a deprecated feature is actually removed,
> * it seems to encourage versioning-related discussions to happen in potentially low-visibility
review requests instead of JIRA tickets,
> * this approach can lead to wrong or misleading information in the code as our versioning
policies evolve and mature, and
> * poor trackability of outstanding deprecations leads to lots of missed opportunities
to remove features already out of their deprecation cycle as we prepare releases.
>
> I would like to propose to use JIRA for tracking deprecations instead.
>
> A possible approach would be:
>
> 1) When a feature becomes deprecated, a JIRA ticket is created for its removal. The ticket
can be referenced in the source code.
> 2) The ticket should be tagged with e.g. `deprecation`, and optimally link back to the
ticket triggering the deprecation.
> 3) A target version is set in collaboration with maintainers of the versioning policy.
> 4) The release process is updated to involve bumping target versions of unfixed deprecation
tickets to the following version.
>
> I believe with this we would be able to better keep track and ultimately fix tech debt,
as well as better improve communicating breaking to users.
>
> Any thoughts?
>
>
> Cheers,
>
> Benjamin

Mime
View raw message