Repository: nushell/nushell
File: crates/nu-experimental/src/options/mod.rs (Rust)

Code before:

    /// Brief description explaining what this option changes.
    ///
    /// Displayed to users in help messages or summaries without needing to visit external docs.
    const DESCRIPTION: &'static str;

    /// Indicates the status of an experimental status.
    ///
    /// Options marked [`Status::OptIn`] are disabled by default while options marked with
    /// [`Status::OptOut`] are enabled by default.
    /// Experimental options that stabilize should be marked as [`Status::DeprecatedDefault`] while
    /// options that will be removed should be [`Status::DeprecatedDiscard`].
    const STATUS: Status;

    /// Nushell version since this experimental option is available.
    ///
    /// These three values represent major.minor.patch version.
    /// Don't use some macro to generate this dynamically as this would defeat the purpose of having
    /// a historic record.
    const SINCE: Version;

    /// PR number that introduced this experimental option.
    ///
    /// To make this work, add a placeholder value here when developing and then, after opening the
    /// PR, update this value.
    const PR: u32;
}

// Export only the static values.
// The marker structs are not relevant and needlessly clutter the generated docs.
pub use example::EXAMPLE;
pub use reorder_cell_paths::REORDER_CELL_PATHS;

// Include all experimental option statics in here.
// This will test them and add them to the parsing list.

/// A list of all available experimental options.
///
/// Use this to show users every experimental option, including their descriptions,
/// identifiers, and current state.
pub static ALL: &[&ExperimentalOption] = &[&EXAMPLE, &REORDER_CELL_PATHS];

#[cfg(test)]
mod tests {
    use std::collections::HashSet;

    use super::*;

    #[test]
    fn assert_identifiers_are_unique() {
        let list: Vec<_> = ALL.iter().map(|opt| opt.identifier()).collect();

Review comment (suggestion):
I get the procedure and that we can always fix it up later, but the process mentioned here makes me think that each experimental option should have a *Tracking Issue*.

That would look similar to those used for rust stabilization.

When you open the PR requiring an experimental option (or planning such a campaign) open a tracking issue along side. 

We then update the main description to link to all relevant issues/PRs and keep track what we need to ensure before we decide on the eventual fate of the experiment. We can point folks to it and solicit feedback or refer to specific issues.

With that as the record keeping location we could easily update details about the behavior we made in follow-up PRs etc. which would be more confusing if we edit the OG PR.

Code after:
    const IDENTIFIER: &'static str;

    /// Brief description explaining what this option changes.
    ///
    /// Displayed to users in help messages or summaries without needing to visit external docs.
    const DESCRIPTION: &'static str;

    /// Indicates the status of an experimental status.
    ///
    /// Options marked [`Status::OptIn`] are disabled by default while options marked with
    /// [`Status::OptOut`] are enabled by default.
    /// Experimental options that stabilize should be marked as [`Status::DeprecatedDefault`] while
    /// options that will be removed should be [`Status::DeprecatedDiscard`].
    const STATUS: Status;

    /// Nushell version since this experimental option is available.
    ///
    /// These three values represent major.minor.patch version.
    /// Don't use some macro to generate this dynamically as this would defeat the purpose of having
    /// a historic record.
    const SINCE: Version;

    /// Github issue that tracks this experimental option.
    ///
    /// Experimental options are expected to end their lifetime by either getting a default feature
    /// or by getting removed.
    /// To track this we want to have a respective issue on Github that tracks the status.
    const ISSUE: u32;
}

// Export only the static values.
// The marker structs are not relevant and needlessly clutter the generated docs.
pub use example::EXAMPLE;
pub use pipefail::PIPE_FAIL;
pub use reorder_cell_paths::REORDER_CELL_PATHS;

// Include all experimental option statics in here.
// This will test them and add them to the parsing list.

/// A list of all available experimental options.
///
/// Use this to show users every experimental option, including their descriptions,
/// identifiers, and current state.
pub static ALL: &[&ExperimentalOption] = &[&EXAMPLE, &REORDER_CELL_PATHS, &PIPE_FAIL];

#[cfg(test)]
mod tests {
    use std::collections::HashSet;

    use super::*;