We've recently started tracking experimental features in the changelog: https://github.com/apache/mesos/blob/e73a778dde10b46e3d03dfa643f7300abbaf951d/CHANGELOG#L156
On Tue, Feb 7, 2017 at 5:50 PM, Ilya Pronin <ipro...@twopensource.com> wrote: > 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 >
