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.bann...@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
