Update documentation for project version computing

Author: MaciejG604

modules/generate-reference-doc/src/main/scala/scala/cli/doc/GenerateReferenceDoc.scala

@@ -574,6 +574,28 @@ object GenerateReferenceDoc extends CaseApp[InternalDocOptions] {
          |```""".stripMargin
     )
 
+    b.section(
+      """## Project version
+        |
+        |A part of the BuildInfo object is the project version. By default, an attempt is made to deduce it using git tags
+        |of the workspace repository. If this fails (e.g. no git repository is present), the version is set to `0.1.0-SNAPSHOT`.
+        |You can override this behaviour by passing the `--project-version` option to Scala CLI or by using a
+        |`//> using projectVersion` directive.
+        |
+        |Please note that only tags that follow the semantic versioning are taken into consideration.
+        |
+        |Values available for project version configuration are:
+        |- `git:tag` or `git`: use the latest stable git tag, if it is older than HEAD then try to increment it
+        |    and add a suffix `-SNAPSHOT`, if no tag is available then use `0.1.0-SNAPSHOT`
+        |- `git:dynver`: use the latest (stable or unstable) git tag, if it is older than HEAD then use the output of
+        |    `-{distance from last tag}-g{shortened version of HEAD commit hash}-SNAPSHOT`, if no tag is available then use `0.1.0-SNAPSHOT`
+        |
+        |The difference between stable and unstable tags are, that the latter can contain letters, e.g. `v0.1.0-RC1`.
+        |It is also possible to specify the path to the repository, e.g. `git:tag:../my-repo`, `git:dynver:../my-repo`.
+        |
+        |""".stripMargin
+    )
+
     b.mkString
   }
 

website/docs/commands/publishing/publish.md

@@ -81,6 +81,17 @@ To override this default value, set the `publish.computeVersion` directive, like
 //> using publish.computeVersion git:tag
 ```
 
+Please note that only tags that follow the semantic versioning are taken into consideration.
+
+Values available for project version configuration are:
+- `git:tag` or `git`: use the latest stable git tag, if it is older than HEAD then try to increment it
+  and add a suffix `-SNAPSHOT`, if no tag is available then use `0.1.0-SNAPSHOT`
+- `git:dynver`: use the latest (stable or unstable) git tag, if it is older than HEAD then use the output of
+  `-{distance from last tag}-g{shortened version of HEAD commit hash}-SNAPSHOT`, if no tag is available then use `0.1.0-SNAPSHOT`
+
+The difference between stable and unstable tags are, that the latter can contain letters, e.g. `v0.1.0-RC1`.
+It is also possible to specify the path to the repository, e.g. `git:tag:../my-repo`, `git:dynver:../my-repo`.
+
 ## Repository settings
 
 A repository is required for the `publish` command, and might need other settings to work fine

website/docs/reference/build-info.md

@@ -90,3 +90,23 @@ object BuildInfo {
 }
 ```
 
+## Project version
+
+A part of the BuildInfo object is the project version. By default, an attempt is made to deduce it using git tags
+of the workspace repository. If this fails (e.g. no git repository is present), the version is set to `0.1.0-SNAPSHOT`.
+You can override this behaviour by passing the `--project-version` option to Scala CLI or by using a
+`//> using projectVersion` directive.
+
+Please note that only tags that follow the semantic versioning are taken into consideration.
+
+Values available for project version configuration are:
+- `git:tag` or `git`: use the latest stable git tag, if it is older than HEAD then try to increment it
+    and add a suffix `-SNAPSHOT`, if no tag is available then use `0.1.0-SNAPSHOT`
+- `git:dynver`: use the latest (stable or unstable) git tag, if it is older than HEAD then use the output of
+    `-{distance from last tag}-g{shortened version of HEAD commit hash}-SNAPSHOT`, if no tag is available then use `0.1.0-SNAPSHOT`
+
+The difference between stable and unstable tags are, that the latter can contain letters, e.g. `v0.1.0-RC1`.
+It is also possible to specify the path to the repository, e.g. `git:tag:../my-repo`, `git:dynver:../my-repo`.
+
+
+