Repository: NomicFoundation/slang
Pull request #1284: define Slang's versioning policy
Author: login: OmarTawfik
Created: 2025-03-15T23:18:55Z | Merged: 2025-03-21T18:44:28Z



Diff:
diff --git a/documentation/public/user-guide/.navigation.md b/documentation/public/user-guide/.navigation.md
index 84546b3c29..0107426dc9 100644
--- a/documentation/public/user-guide/.navigation.md
+++ b/documentation/public/user-guide/.navigation.md
@@ -7,3 +7,4 @@
 - [6. Query Language](./06-query-language/)
 - [7. Semantic Analysis](./07-semantic-analysis/)
 - [8. Examples](./08-examples/)
+- [9. Appendix](./09-appendix/)
diff --git a/documentation/public/user-guide/09-appendix/.navigation.md b/documentation/public/user-guide/09-appendix/.navigation.md
new file mode 100644
index 0000000000..fe94712a29
--- /dev/null
+++ b/documentation/public/user-guide/09-appendix/.navigation.md
@@ -0,0 +1,2 @@
+- [9. Appendix](./index.md)
+- [9.1. Slang Versioning Policy](./01-slang-versioning-policy/index.md)
diff --git a/documentation/public/user-guide/09-appendix/01-slang-versioning-policy/index.md b/documentation/public/user-guide/09-appendix/01-slang-versioning-policy/index.md
new file mode 100644
index 0000000000..f9024f7c29
--- /dev/null
+++ b/documentation/public/user-guide/09-appendix/01-slang-versioning-policy/index.md
@@ -0,0 +1,44 @@
+# 9.1. Slang Versioning Policy
+
+Slang is not tied to a specific Solidity version, and can be used to analyze multiple Solidity versions with the same API.
+At the same time, Slang's own API needs to be consistent and stable as new versions of Solidity are released.
+
+The NPM package uses [Semantic Versioning](https://semver.org/) and [CHANGELOG.md](https://github.com/NomicFoundation/slang/blob/main/CHANGELOG.md)
+to communicate such changes in the form of `{MAJOR}.{MINOR}.{PATCH}` versions, to report breaking changes, new features, and bug fixes (respectively).
+But it is not really designed to report two (often orthogonal) kinds of changes: changes in Slang's APIs, and changes in the Solidity language itself.
+
+Therefore, it is important to define and follow a clear versioning policy for Slang, that will make this distinction clear.
+Each changelog entry will contain a link to the pull request that introduced the change. The pull request will contain a description
+of the change, its impact on our APIs, the Solidity language, and any potential impact on the users.
+
+## Major Version Updates
+
+These are `{MAJOR}.0.0` releases, and they are intended to represent breaking changes in Slang's APIs.
+For example, when an existing API is removed, or replaced with a different one, and will often require
+manual intervention from the user to update their code.
+
+These releases are only done when absolutely necessary, and are not expected to happen often.
+They are often accompanied by detailed announcements, explaining the motivation behind it.
+
+## Minor Version Updates
+
+These are `X.{MINOR}.0` releases, and they are intended to represent one of two things:
+
+1. A new Slang API or feature that is backwards compatible with previous versions. While users should take note of it,
+   in case it is useful to them, the existing APIs should continue to work without any changes.
+2. Adoption of a new Solidity version, which can often impact the structure of the CST (adding or changing existing nodes),
+   or user-authored tree queries. This can possibly be a breaking change if users were using the specific node kinds
+   that were updated in the new version, so they should also take note of it, especially if they want to support
+   multiple (or latest) Solidity versions.
+
+Because of this, users might want to depend on the Slang version in their `package.json` using the `~` operator
+instead of `^`, which enforces compatibility with the minor version, but will allow for patch updates.
+
+Slang intends to always keep up with Solidity language updates, and promptly implement user feedback and feature requests.
+As such, these releases will happen semi-regularly, and we advise users to review the changelog when they happen.
+
+## Patch Version Updates
+
+These are `X.X.{PATCH}` releases, and they are intended to represent bug fixes and minor improvements.
+While they can impact user code (if the older version had a bug, which is now fixed), they are not expected to break
+Slang APIs, and should be adopted as soon as possible, to make sure user code is always performing correctly.
diff --git a/documentation/public/user-guide/09-appendix/index.md b/documentation/public/user-guide/09-appendix/index.md
new file mode 100644
index 0000000000..6bd349c33c
--- /dev/null
+++ b/documentation/public/user-guide/09-appendix/index.md
@@ -0,0 +1,3 @@
+# 9. Appendix
+
+- [9.1. Slang Versioning Policy](./01-slang-versioning-policy/index.md)
diff --git a/documentation/public/user-guide/index.md b/documentation/public/user-guide/index.md
index 9a1e566d42..1f34a64e63 100644
--- a/documentation/public/user-guide/index.md
+++ b/documentation/public/user-guide/index.md
@@ -8,3 +8,4 @@
 - [6. Query Language](./06-query-language/index.md)
 - [7. Semantic Analysis](./07-semantic-analysis/index.md)
 - [8. Examples](./08-examples/index.md)
+- [9. Appendix](./09-appendix/index.md)


Reviews:
user: login: alcuadrado
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-19T00:19:55Z
user: login: stefanoban
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-19T10:34:44Z
user: login: stefanoban
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-19T11:18:48Z
user: login: beta-ziliani
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-19T14:17:36Z
user: login: OmarTawfik
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T10:49:20Z
user: login: OmarTawfik
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T10:51:25Z
user: login: stefanoban
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-03-20T17:24:08Z

Review comments:
diff_hunk: @@ -0,0 +1,39 @@
+# 9.1. Slang Versioning Policy
+
+Slang is not tied to a specific Solidity version, and can be used to analyze multiple Solidity versions with the same API.
+At the same time, Slang's own API needs to be consistent and stable as new versions of Solidity are released.
+
+The NPM package uses [Semantic Versioning](https://semver.org/) and [CHANGELOG.md](https://github.com/NomicFoundation/slang/blob/main/CHANGELOG.md)
+to communicate such changes in the form of `{MAJOR}.{MINOR}.{PATCH}` versions, to report breaking changes, new features, and bug fixes (respectively).
+But it is not not really designed to report two (often orthogonal) kinds of changes: changes in Slang's APIs, and changes in the Solidity language itself.
+
+Therefore, it is important to define and follow a clear versioning policy for Slang, that will make this distinction clear.
+Each changelog entry will contain a link to the pull request that introduced the change. The pull request will contain a description
+of the change, its impact on our APIs, the Solidity language, and any potential impact on the users.
+
+## Major Version Updates
+
+These are `{MAJOR}.0.0` releases, and they are intended to represent breaking changes in Slang's APIs.
+For example, when an existing API is removed, or replaced with a different one, and will often require
+manual intervention from the user to update their code.
+
+These releases are only done when absolutely necessary, and are not expected to happen often.
+They are often accompanied by detailed announcements, explaining the motivation behind it.
+
+## Minor Version Updates
path: documentation/public/user-guide/09-appendix/01-slang-versioning-policy/index.md
user: login: alcuadrado
body: Maybe this section could include a comment explaining that changes in the CST and the like are technically breaking changes, but due to changes in the language, and not Slang's own APIs.

Also, it could recommend installing with `~` instead of `^` for those that want total stability. 
created_at: 2025-03-19T00:19:55Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,39 @@
+# 9.1. Slang Versioning Policy
+
+Slang is not tied to a specific Solidity version, and can be used to analyze multiple Solidity versions with the same API.
+At the same time, Slang's own API needs to be consistent and stable as new versions of Solidity are released.
+
+The NPM package uses [Semantic Versioning](https://semver.org/) and [CHANGELOG.md](https://github.com/NomicFoundation/slang/blob/main/CHANGELOG.md)
+to communicate such changes in the form of `{MAJOR}.{MINOR}.{PATCH}` versions, to report breaking changes, new features, and bug fixes (respectively).
+But it is not not really designed to report two (often orthogonal) kinds of changes: changes in Slang's APIs, and changes in the Solidity language itself.
path: documentation/public/user-guide/09-appendix/01-slang-versioning-policy/index.md
user: login: stefanoban
body: ```suggestion
But it is not really designed to report two (often orthogonal) kinds of changes: changes in Slang's APIs, and changes in the Solidity language itself.
```
created_at: 2025-03-19T10:34:44Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,39 @@
+# 9.1. Slang Versioning Policy
+
+Slang is not tied to a specific Solidity version, and can be used to analyze multiple Solidity versions with the same API.
+At the same time, Slang's own API needs to be consistent and stable as new versions of Solidity are released.
+
+The NPM package uses [Semantic Versioning](https://semver.org/) and [CHANGELOG.md](https://github.com/NomicFoundation/slang/blob/main/CHANGELOG.md)
+to communicate such changes in the form of `{MAJOR}.{MINOR}.{PATCH}` versions, to report breaking changes, new features, and bug fixes (respectively).
+But it is not not really designed to report two (often orthogonal) kinds of changes: changes in Slang's APIs, and changes in the Solidity language itself.
+
+Therefore, it is important to define and follow a clear versioning policy for Slang, that will make this distinction clear.
+Each changelog entry will contain a link to the pull request that introduced the change. The pull request will contain a description
+of the change, its impact on our APIs, the Solidity language, and any potential impact on the users.
+
+## Major Version Updates
+
+These are `{MAJOR}.0.0` releases, and they are intended to represent breaking changes in Slang's APIs.
+For example, when an existing API is removed, or replaced with a different one, and will often require
+manual intervention from the user to update their code.
+
+These releases are only done when absolutely necessary, and are not expected to happen often.
+They are often accompanied by detailed announcements, explaining the motivation behind it.
+
+## Minor Version Updates
+
+These are `X.{MINOR}.0` releases, and they are intended to represent one of two things:
+
+1. A new Slang API or feature that is backwards compatible with previous versions. While users should take note of it,
+   in case it is useful to them, the existing APIs should continue to work without any changes.
+2. Adoption of a new Solidity version, which can often impact the structure of the CST (adding or changing existing nodes),
path: documentation/public/user-guide/09-appendix/01-slang-versioning-policy/index.md
user: login: stefanoban
body: For the cases when adding support for a new Solidity version impacts the structure of the CST and creates a breaking change for earlier Solidity versions, why not have a major release (and follow SemVer)? How often is this happening?
created_at: 2025-03-19T11:18:48Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,39 @@
+# 9.1. Slang Versioning Policy
+
+Slang is not tied to a specific Solidity version, and can be used to analyze multiple Solidity versions with the same API.
+At the same time, Slang's own API needs to be consistent and stable as new versions of Solidity are released.
+
+The NPM package uses [Semantic Versioning](https://semver.org/) and [CHANGELOG.md](https://github.com/NomicFoundation/slang/blob/main/CHANGELOG.md)
+to communicate such changes in the form of `{MAJOR}.{MINOR}.{PATCH}` versions, to report breaking changes, new features, and bug fixes (respectively).
+But it is not not really designed to report two (often orthogonal) kinds of changes: changes in Slang's APIs, and changes in the Solidity language itself.
+
+Therefore, it is important to define and follow a clear versioning policy for Slang, that will make this distinction clear.
+Each changelog entry will contain a link to the pull request that introduced the change. The pull request will contain a description
+of the change, its impact on our APIs, the Solidity language, and any potential impact on the users.
+
+## Major Version Updates
+
+These are `{MAJOR}.0.0` releases, and they are intended to represent breaking changes in Slang's APIs.
+For example, when an existing API is removed, or replaced with a different one, and will often require
+manual intervention from the user to update their code.
+
+These releases are only done when absolutely necessary, and are not expected to happen often.
+They are often accompanied by detailed announcements, explaining the motivation behind it.
+
+## Minor Version Updates
+
+These are `X.{MINOR}.0` releases, and they are intended to represent one of two things:
+
+1. A new Slang API or feature that is backwards compatible with previous versions. While users should take note of it,
+   in case it is useful to them, the existing APIs should continue to work without any changes.
+2. Adoption of a new Solidity version, which can often impact the structure of the CST (adding or changing existing nodes),
path: documentation/public/user-guide/09-appendix/01-slang-versioning-policy/index.md
user: login: beta-ziliani
body: It will happen in the next version 😢  because of https://github.com/NomicFoundation/slang/issues/1282
created_at: 2025-03-19T14:17:36Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,39 @@
+# 9.1. Slang Versioning Policy
+
+Slang is not tied to a specific Solidity version, and can be used to analyze multiple Solidity versions with the same API.
+At the same time, Slang's own API needs to be consistent and stable as new versions of Solidity are released.
+
+The NPM package uses [Semantic Versioning](https://semver.org/) and [CHANGELOG.md](https://github.com/NomicFoundation/slang/blob/main/CHANGELOG.md)
+to communicate such changes in the form of `{MAJOR}.{MINOR}.{PATCH}` versions, to report breaking changes, new features, and bug fixes (respectively).
+But it is not not really designed to report two (often orthogonal) kinds of changes: changes in Slang's APIs, and changes in the Solidity language itself.
path: documentation/public/user-guide/09-appendix/01-slang-versioning-policy/index.md
user: login: OmarTawfik
body: Done.

created_at: 2025-03-20T10:49:19Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,39 @@
+# 9.1. Slang Versioning Policy
+
+Slang is not tied to a specific Solidity version, and can be used to analyze multiple Solidity versions with the same API.
+At the same time, Slang's own API needs to be consistent and stable as new versions of Solidity are released.
+
+The NPM package uses [Semantic Versioning](https://semver.org/) and [CHANGELOG.md](https://github.com/NomicFoundation/slang/blob/main/CHANGELOG.md)
+to communicate such changes in the form of `{MAJOR}.{MINOR}.{PATCH}` versions, to report breaking changes, new features, and bug fixes (respectively).
+But it is not not really designed to report two (often orthogonal) kinds of changes: changes in Slang's APIs, and changes in the Solidity language itself.
+
+Therefore, it is important to define and follow a clear versioning policy for Slang, that will make this distinction clear.
+Each changelog entry will contain a link to the pull request that introduced the change. The pull request will contain a description
+of the change, its impact on our APIs, the Solidity language, and any potential impact on the users.
+
+## Major Version Updates
+
+These are `{MAJOR}.0.0` releases, and they are intended to represent breaking changes in Slang's APIs.
+For example, when an existing API is removed, or replaced with a different one, and will often require
+manual intervention from the user to update their code.
+
+These releases are only done when absolutely necessary, and are not expected to happen often.
+They are often accompanied by detailed announcements, explaining the motivation behind it.
+
+## Minor Version Updates
path: documentation/public/user-guide/09-appendix/01-slang-versioning-policy/index.md
user: login: OmarTawfik
body: Done.
created_at: 2025-03-20T10:51:24Z
author_association: CONTRIBUTOR

PR comments:
user: login: changeset-bot[bot]
created_at: 2025-03-15T23:18:59Z
body: ###  ⚠️  No Changeset found

Latest commit: b24438d157194cca00c8f7ad44e844fc91f58402

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. **If these changes should result in a version bump, you need to add a changeset.**

<details><summary>This PR includes no changesets</summary>

  When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

</details>

[Click here to learn what changesets are, and how to add one](https://github.com/changesets/changesets/blob/main/docs/adding-a-changeset.md).

[Click here if you're a maintainer who wants to add a changeset to this PR](https://github.com/OmarTawfik-forks/slang/new/version-bump-policy?filename=.changeset/silent-dingos-type.md&value=---%0A%22%40slang-private%2Fsolidity-user-guide%22%3A%20patch%0A---%0A%0Adefine%20Slang's%20versioning%20policy%0A)


author_association: NONE
user: login: alcuadrado
created_at: 2025-03-19T00:18:29Z
body: This looks good.
author_association: MEMBER