diff --git a/readme.adoc b/readme.adoc index dbc4538..9296a20 100644 --- a/readme.adoc +++ b/readme.adoc @@ -1,8 +1,6 @@ -= RISC-V Specification Template += RISC-V B -This repository serves as a blueprint for creating GitHub repositories within the RISC-V organization for the purpose of developing specifications. The template aims to facilitate and standardize the process of specification development. - -NOTE: If you are viewing this in a specification repository, kindly update the title for this section and provide an introduction relevant to your repository. +It has been recognized that there is need to officially standardize a "B" extension - that represents the collection of the Zba, Zbb, Zbs extensions - for the sake of consistency and conciseness across toolchains and how they identify support for these bitmanip extensions (which, for example, are mandated in RVA and RVB profiles). In conjunction with this an official definition of the misa.B bit will be established - along the lines of misa.B=1 indicating support for at least these three extensions (and misa.B=0 indicating that one or more are not supported). == License @@ -26,75 +24,11 @@ To build the document, you'll need the following tools installed on your system: === Cloning the Repository -`git clone --recurse-submodules https://github.com/riscv/docs-spec-template.git` - -=== Versioning, Customization and Makefile Variables - -This section provides an overview of the environment variables used in our Makefile. These variables include DATE, VERSION, and REVMARK. - -* `DATE`: Represents the current date. The default value is generated using the date command on Unix-based systems, formatted as "YYYY-MM-DD". -* `VERSION`: Represents the version of the specification being built. By default, this is set to 'v0.0.0'. You can change this to a different value, like 'v1.0.0', 'v1.1.0', etc., based on the current version of your specification. -* `REVMARK`: This represents a revision marker for the project. Its default value is 'Draft'. You may want to change this to something like 'Release' or 'Stable'. -* `PDF_RESULT`: Specifies the name of the output PDF file. -* `DOCKER_RUN`: Defines the Docker run command used when Docker is available. - -==== Versioning Strategy - -In a nutshell, the versioning strategy is as follows: - -```bash -[Start] - | - V -1.0.0-draft[#] --> (Revisions) --> 1.0.0-draft[#] (last draft) - | - V -1.0.0-rc[#] --> (Revisions) --> 1.0.0-rc[#] (last release candidate) - | - V -[Approval] - | - V -1.0.0 (Approved/Ratified) - | - V -(Minor changes, Fixes, Compatible extensions) --> 1.1.0 - | - V -(Corrections, Editorial changes) --> 1.1.1 - | - V -(Incompatible changes, Major new features) --> 2.0.0 -``` - -link:https://docs.google.com/document/d/1ZO3clTdgbm-t6r8GMDQ7CypWl68_3ZeYuHl4e-cS280/edit[RISC-V International has a policy for versioning] -. The purpose of this policy is to ensure consistency and clarity in the versioning of RISC-V artifacts, which can be comprehended by both the RISC-V community and external parties. This policy adheres to Semantic Versioning 2.0.0 (MAJOR.MINOR.PATCH). - -The first ratified version of any artifact is expected to be 1.0.0. The policy outlines specific versioning conventions for different stages of specification development: 1.0.0-draft1 for drafts, 1.0.0-rc1 for release candidates, and 1.0.0 for approved and ratified specifications. Furthermore, the use of build-date metadata is encouraged for non-release versions. - -The MAJOR.MINOR.PATCH paradigm is explained as: PATCH for corrections or editorial changes, MINOR for fixes and compatible extensions with limited new functionality, and MAJOR for incompatible changes or significant new features. The policy is effective immediately upon approval. - -Examples: - -* Specification Development - Suppose a new RISC-V specification is being developed. Its version might start as 1.0.0-draft1 for the first draft, then proceed to 1.0.0-rc1 when it reaches the release candidate stage (1.0.0-rc2, 1.0.0-rc3, etc...), and finally settle at 1.0.0 when it's approved and ratified. - -* Update Types - If the ratified specification undergoes a minor update, incorporating fixes or compatible extensions with limited new functionality, it would change to 1.1.0. If there are only corrections or editorial modifications, the version would move to 1.0.1. For incompatible changes or major new features, the version would leap to 2.0.0. - -* Metadata Tagging - Non-release versions of the specification can be tagged with the build date. For example, if a draft version is prepared on June 29, 2023, it could be tagged as 1.0.0-draft1+20230629. - -==== Setting Environment Variables - -These variables can be overridden by setting environment variables on your system. Here's how you can do it in Linux and MacOS: - -```bash -export VERSION=v1.2.3 -export REVMARK=Release -export PDF_RESULT=spec.pdf -``` +`git clone --recurse-submodules https://github.com/riscv/riscv-b.git` === Building the Documentation -To start the build process, run `cd ./docs-spec-template && make build`. +To start the build process, run `cd ./riscv-b && make build`. The Makefile script will check the availability of Docker on your system: