mesos-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ilya Pronin <ipro...@twopensource.com>
Subject Re: Tracking deprecated features
Date Tue, 07 Feb 2017 16:50:02 GMT
I agree with Neil that deprecation/experimental status should be
duplicated on the website/docs. Users shouldn't have to scan JIRA in
search for documentation.

On Tue, Feb 7, 2017 at 4:33 PM, Neil Conway <neil.conway@gmail.com> wrote:
> 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