This sounds good to me. A couple thoughts.
(1) Can we first define the meaning of "experimental" vs "stable" so that
it's clear to users and ourselves? This definition should encompass when we
want to call a feature experimental vs just building it and immediately
calling it stable. For example, if we added some simple additional
functionality (e.g. a new type of health check) we may not want to bother
calling it experimental, otherwise we might get stuck with a lot of things
sitting in experimental and having a hard time knowing when to call them
stable.
(2) Would you like to propose a format that fits cleanly into our existing
format?
I suspect we'll also want a section for things that have "graduated" to
stable in the release. Otherwise the user has to infer this? For example:
The following features have graduated from experimental to stable in 1.1.0:
* Support for flux capacitors is now considered stable: there are no
longer any
major issues and this feature is being used without issues by a number
of users
in production.
* The following features present in 1.1.0 are considered experimental *
* Support for warp drives: there are still a number of known issues
related to
warp drives causing servers to experience time dilation and fail within
days
as opposed to years. Not yet recommended for production usage.
For JIRA, a graduation epic sounds nice if we know what the issues are.
Otherwise we might want to use 'component' and have dashboards (e.g.
component = "warp drives" && type = Bug). Tangentially, I suspect that
having component-level dashboards might be a nice way for maintainers to
keep tabs on bug reports coming in (so long as we have community members
helping out to tag the right components), and ideally maintainers could
have dashboards that include commits going in to their area as well, I
digress. :)
On Thu, Nov 3, 2016 at 5:05 AM, Avinash Sridharan <[email protected]>
wrote:
> I like the idea of having experimental features explicitly being called out
> in the change log. In addition, would it make sense to mandate that
> experimental features have a JIRA associated with them? Probably tag them
> with a label, and we can have a dashboard with the experimental features.
> This should be the responsibility of the shepherd/developer
> introducing/maintaining the feature. The JIRA itself need not be an epic,
> but a release place holder that can link to other epics/bugs. When the
> feature graduates mark them closed and tag them as production ready (or
> something more appropriate).
>
> Will be easier for operators/users to file bugs against these features and
> also track their progress. We already do this in some sense when we
> introduce the feature. But once we release the feature (marked as
> experimental) the JIRAs (epics) are usually closed and across releases the
> features evolve into multiple epics and its hard to track the progress for
> the uninitiated.
>
> While change logs are pretty important, from an operators standpoint, I
> feel having JIRAs will give a nice insights into the history of a feature
> and give a clearer picture to developers and users alike in the community.
>
> On Thu, Nov 3, 2016 at 2:48 PM, Alex Rukletsov <[email protected]>
> wrote:
>
> > Every experimental feature graduating from experimental should be
> > explicitly called out at the top of the log. We probably haven't been
> > consistent in the past, but it should be easier for a release manager to
> > remember when adjusting the list of still experimental features.
> >
> > On Wed, Nov 2, 2016 at 7:06 PM, Zhitao Li <[email protected]> wrote:
> >
> > > (speaking from both a contributor and user perspective)
> > >
> > > Definitely +1 for improve visibility of experimental features, and I
> > think
> > > the proposal is definitely helpful for people to read it.
> > >
> > > In terms of expectation management, one thing from the user perspective
> > is
> > > when an experimental feature will graduate into stable, because a
> > > responsible user might hold-off actual (or full) adoption until that
> > > happens, and they need to plan accordingly. Have a way to track what
> > items
> > > the owner considers necessary for a feature to become stable is quite
> > > important in such a case (not everyone has the luxury to comb through
> > JIRA
> > > boards for contexts, or talk to the direct owner of the the feature).
> > >
> > > On Tue, Nov 1, 2016 at 5:28 PM, Alex Rukletsov <[email protected]>
> > > wrote:
> > >
> > > > Folks,
> > > >
> > > > Additionally to the "known bugs" proposal in a parallel thread, we
> > think
> > > > that maintaining a list of still experimental features for each minor
> > > > release will significantly help users
> > > > to adjust their expectations.
> > > >
> > > > Our suggestion is to include a new section into the CHANGELOG called
> > > > "Experimental Features" starting with the upcoming 1.1.0 release.
> > > > Populating this section should be relatively easy: take the contents
> of
> > > > this section from the previous minor release, remove features
> declared
> > > > stable, and add new experimental features.
> > > >
> > > > With this change users will have a complete overview of experimental
> > > > functionality per release, without searching the CHANGELOG for when
> and
> > > > whether a certain feature became production-ready.
> > > >
> > > > What do you think?
> > > >
> > > > AlexR.
> > > >
> > >
> > >
> > >
> > > --
> > > Cheers,
> > >
> > > Zhitao Li
> > >
> >
>
>
>
> --
> Avinash Sridharan, Mesosphere
> +1 (323) 702 5245
>
