formalize how to introduce changes into the compiler

[xunilrj]

Rendered

[ironcev]

Proposal is to add additional sub-chapter or a paragraph under the Feature flags chapter. E.g., Feature flags and #[cfg] attribute.

Every experimental flag provides an argument that can be used inside of the #[cfg] attribute. This enables conditional compilation of Sway code only if the experimental feature is opted in. The argument is formed out of the feature flag name prefixed with the experimental. E.g., #[cfg(experimental_composable_storage).

We need this support, because developing a new feature does not mean only extending the compiler, but often also the standard libraries. E.g., when developing new storage, we will have different implementations of storage types like, e.g., StorageVec. We want those implementations to coexist with those expected by the current implementation of storage in the compiler. Supporting #[cfg], of course, goes beyond Sway standard libraries. 3rd party libraries can be adapted as well to continuously follow a new feature development. Also, we had the situation already that tests needed to be conditionally compiled to support different contract IDs for encoding v0 and v1.

[ironcev]

Proposal is to explicitly mention that we will not support Sway Editions, the way Rust does it. Once an experimental feature gets promoted to standard behavior, it cannot be turned off anymore in that version and newer versions of the compiler. In other words, it is not possible to take a compiler of a certain version and "ask" it to behave the same as some older version.

[ironcev]

How are we going to approach testing the features on CI and in general?

In a near future we will have several features being developed in parallel, all behind feature flags, all with their code in master, either in development or fully developed and waiting for becoming the default behavior. All of them will have their tests or some tests adapted to work with and without the feature.

Can we elaborate more on this in the RFC? Some of the topics:

• how features will be tested in CI?
• how artefacts that can differ in features like ABI JSON or storage slots will be defined?
• how will different features be conditionally compiled in test code? We will need both #[cfg] and #![cfg].
• how to specify feature-specific filecheck directives or snapshots?

[kayagokalp]

Just left a single question, it is great that this is getting formalized :)

Out of the scope of this PR but something that we should start thinking about is the is the question that we are putting aside for some time now. The fact that forc and rest of the plugins are getting released at the same time as the compiler does. Which means we do not have any way conveying the breakage in those parts of the released stuff.

To make my point clear, let me give an extreme example: any change to the dependency declaration syntax etc in the Forc.toml would mean all existing projects are no longer building and thus breaking in terms of forc, subsequently the end users as well. So marking that forc version with a minor bump over the last one (imagine no breaking changes included after last release in terms of the compiler), will convey the idea that the project should still be building. But in reality nothing will build.

This comment of mine would be completely irrelevant to this PR, if the compiler had any other entry, like rustc. As then it becomes the forc's own versioning discussion and totally separate from the compiler. But currently forc is the only entrance to the compiler and only way of using it. So it might make sense to discuss this scenario as well for compiler versioning.

[ironcev]

Looking forward to have the proposal put in practice! (The suggested changes are only typos popping out of the final quick-read 😄)

[Voxelot]

following from the torvolds line, "WE DO NOT BREAK USERSPACE!" Should we clarify that patches will respect semver expectations? ie. minor releases and patches don't require any user intervention? Unless we are pre 1.0, then minor releases are treated like major breaking ones.

Its not clear to me from the rolling release scheme description here what guarantees - if any - we are providing to our users and how the versions signal changes.

For example, if the next version after 1.0 is 1.1, at what point do we bump to 2.0?

if a security or bug fix breaks an existing user program, we should maybe yank versions instead of pushing a patch that might break userspace.

[IGI-111]

We should follow the semver guidelines here. Use major for breaking changes, minor for nonbreaking changes and patch for bug fixes only.

A simple mention that we do so and that this document is meant to elucidate what we consider breaking should suffice.

[xunilrj]

Done.

[Voxelot]

doesnt need to be specified here necessarily, but if a flag is disabled we should just emit a warning to the user to ensure the presence of flag that is no longer used doesn't break or prevent compilation in any way. ie. if i set an experimental flag on my CI, and then it later becomes stable, we shouldn't throw any errors because the flag is no longer used imo. If flags are specified that never existed then i think it's fair to throw an error to the user so they know it's not working as they may expect.

[IGI-111]

I think forcing you to update your flags when features are stabilized is a feature, not a bug.

[xunilrj]

I agree with @IGI-111. This does not mean that we can not generate warnings along the way, before removing the flag.

[Voxelot]

this may impact abi verification tools (cc @sdankel)

[IGI-111]

Surely such tools should only use stable compiler features. We may want to extend support which requires recoding what flags are used on top of the compiler version, but we should not encourage people to use experimental features. In fact this should be more discouraged than it is in Rust given our environment.

[xunilrj]

I vote for this to be dealt in another RFC.