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