Release process proposal

[ematipico]

Few days ago on discord I proposed to make a release of the new things we had done on the formatter (some new option and some bug fix), and that raised few question about how often we should do releases, what to release and how can we do releases without shipping things that are still unstable/experimental.

Two different topics, two different proposals.

[ematipico]

Release cadence

How often should we do a release? How do we handle minor releases and patch releases?

Some projects release at a certain time:

• Rust does its release every six weeks, if a feature doesn't make the cut, it's released in the next release, patch releases have high priority.
• eslint seems to do a weekly release on Friday and it's always a minor (correct me if am wrong);

Other projects have don't have a clear cadence (probably because maintained by few people or because there isn't need).

As we have a big team working on the project, I think we can make a commitment and try to stick to it, so the community
knows when to expect a new release (with potential features).

Proposal

• patch releases of bugs that are blocking have a priority over any feature/other bugfix; how to label
  a bug "blocking", I suppose they can be the ones that don't have a workaround or really blocks a developer from working;
• a four week release that will contain not blocking fixes and (if there are any) features;
• if a release contains new feature that worth an explanation, we should have a blog post;

[yassere]

How much direct attention and care do we plan to put into each release? If we have a weekly release that’s fully automated, would that just be a glorified nightly?

[MichaReiser]

I like the idea of having a fixed cadence for releases. I would recommend that we align the project milestones and release cadence (by changing either of them).

[ematipico]

I like the idea of weekly releases, although rather than a Friday (which makes sense for a volunteer effort), we should target Monday or Tuesday.

Nightly releases were good and I think we can reintroduce them once we are comfortable. I am not sure we are in a position of offering weekly releases. Each release requires some preparation from the team: update documentation on the website, changelog, possible blog post, etc. Seems lot of work. Did you have something in particular in mind?

We may want to even plan around a major version every 6 months or so, as it may help us making long-term plans, especially around compatibility and introducing large features.

Good point! Probably major releases could be in sync with the release of new tools and (of course) breaking changes.

[NicholasLYang]

I like the idea of weekly releases for minor changes, then monthly announcement/documentation changes. That way we can have a standard "here's the cool stuff we added" post every month.

[ematipico]

Based on the feedback received, it seems that some people expressed some interested in weekly releases, although we are missing proposal on how to achieve that. Automatic? Manual? What about the changelog?

Final decision

• patch releases of bugs that are blocking have a priority over any feature/other bugfix; how to label
  a bug "blocking", I suppose they can be the ones that don't have a workaround or really blocks a developer from working;
• a four week release that will contain non-blocking fixes and (if there are any) features; Tuesday will be the day of the release. Having it on a Monday doesn't seem ideal as people come from the weekend. And it will pressure the team into prepare the release on a Friday;
• if a release contains new features that's worth an explanation, we should have a blog post; this is arbitrary and it's up to the team to decide if a new minor release needs to have a blog post;

The decisions was taken are based on the fact that we don't have an automated process to make releases.

Once we have more time to make an automatic release (auto generation of changelog, better workflows and versioning, publish documentation only after the release, etc.), I think it's worth revisit the decision with another proposal. For example, weekly releases.

[ematipico]

Experimental features

Having a recurring release opens us to the risk of merging new features that are not ready to be published, for different reasons, e.g. multiple PRs are needed to create the feature, performance regressions, etc.

These are features that will eventually be merged, regardless of the effort. They are not experiments that we plan
to "test" and ditch in case the "experiment" didn't go well.

So, the wording can change, we can call it "experimental", "feature flags", "WIP features", etc., but these features will eventually be the default of Rome.

Proposal

• Having a cental crate where all tools will depend from; this is something that we have to do regardless, so starting this work sooner rather than later will benefit everyone. We can have a rome_config crate, or use rome_core that we have already. This is where tools will check if they should hide the experimental* features.
• We can leverage Rust language (macros, directives, etc.) to hide these features under the experimental* feature flag.
• Having a --experimental* flag at CLI level that unlocks these work in progress features; all commands should support this flag.
• Having a "experimental" option in all the editors we support.
• We can different workflows to test these experimental* features.

*the name is arbitrary and not set on stone

[ematipico]

I would have preferred a counter proposal instead of jumping straight to the code.

Anyway, from your draft PR, could you propose how and if us developers should document the features that are in WIP?

Should user able to opt-in these flags with the release version of the binary?

[yassere]

I would have preferred a counter proposal instead of jumping straight to the code.

The code is the counter proposal. It seemed easier than going back and forth with comments, and we can always just close the draft PR if we don’t like it.

could you propose how and if us developers should document the features that are in WIP?

I modified the macro to allow for adding a doc comment that shows up whenever you hover over any usage of the flag:

declare_feature_flags!(
    /// A new way of linebreaking
    new_linebreaking,
    /// A new way of spacing
    new_spacing
);

There's more we can borrow from Rust's flags like documenting the issue associated with the feature.
In our case, I think that feature flags should be temporary and deleted as soon as possible rather than documenting them long-term.

Should user able to opt-in these flags with the release version of the binary?

If we're primarily intending these feature flags as a way to merge unfinished code without disrupting releases, then we should discourage their usage by consumers (and maybe print appropriate warnings). But it can still be useful to have them available in the release binary for benchmarking and testing.

[ematipico]

Sorry @yassere, I should have expanded. With documenting I meant what I said in my counter proposal. Having a MD document where to track the unfinished features. Should we? Are comments enough? Or Do you think the rome_feature will be enough on the long run?

Overall, I like the proposal!

[yassere]

Going back to the distinction that Micha was making:

1. Being able to ship stable Rome releases where unfinished features are disabled without the need for feature branches
2. Allow users to use unfinished features

Since we're currently only solving case 1, I think that comments are sufficient documentation.
I agree that case 2 should be deferred and we'd likely want better documentation for those flags. If we decide to pursue this proposal, we'll want to revise my PR to make it clear that those are "unfinished" feature flags. If we later add "experimental" feature flags for public usage, they should be clearly differentiated.

Overall, I like the proposal!

Thanks! I think it's mostly just what @MichaReiser was suggesting above.
I haven't put much thought yet into the details of the implementation itself.

[ematipico]

The PR was merged, which means that the team as arrived at a consensus. Thank you team!