diff --git a/.github/workflows/build-pdf.yml b/.github/workflows/build-pdf.yml index ae261c2..b7be4dd 100644 --- a/.github/workflows/build-pdf.yml +++ b/.github/workflows/build-pdf.yml @@ -1,79 +1,73 @@ -# This workflow installs dependencies for PDF generation, generates the PDF, -# and uploads the PDF as an artifact. - -name: Build Document PDF +name: Create Specification Document +# The workflow is triggered by pull request, push to main, and manual dispatch. on: - push: - branches: - - main + workflow_dispatch: + inputs: + version: + description: 'Release version, e.g. X.Y.Z:' + required: true + type: string + revision_mark: + description: 'Set revision mark as Draft, Release or Stable:' + required: true + type: string + default: 'Draft' + prerelease: + description: 'Tag as a pre-release?' + required: false + type: boolean + default: true + draft: + description: 'Create release as a draft?' + required: false + type: boolean + default: false pull_request: + push: branches: - main - workflow_dispatch: - workflow_call: - outputs: - name: - description: "The base name of the pdf file (without .pdf extensions)" - value: ${{ jobs.build.outputs.name }} - pdf-name: - description: "The name of the pdf file (with .pdf extensions)" - value: ${{ jobs.build.outputs.pdf-name }} jobs: build: - runs-on: ubuntu-22.04 - - env: - NAME: example-spec - APT_PACKAGES_FILE: ${{ github.workspace }}/dependencies/apt_packages.txt - BUNDLE_GEMFILE: ${{ github.workspace }}/dependencies/Gemfile - BUNDLE_BIN: ${{ github.workspace }}/bin - NPM_PACKAGE_FOLDER: ${{ github.workspace }}/dependencies - outputs: - name: ${{ steps.step1.outputs.name }} - pdf-name: ${{ steps.step2.outputs.pdf-name }} + runs-on: ubuntu-latest + steps: - - name: Set outputs.name - id: step1 - run: echo "name=$NAME" >> $GITHUB_OUTPUT - - name: Set outputs.pdf-name - id: step2 - run: echo "pdf-name=$NAME.pdf" >> $GITHUB_OUTPUT + # Step 1: Checkout the repository - name: Checkout repository uses: actions/checkout@v3 with: - submodules: 'true' - - name: Install Ubuntu packages - run: | - sudo apt-get update - grep -vE '^#' ${APT_PACKAGES_FILE} | xargs sudo apt-get install --yes --no-install-recommends - # Ruby for asciidoctor - - name: Setup Ruby and Gemfile content - uses: ruby/setup-ruby@v1 - with: - ruby-version: "2.6" - bundler-cache: true - # Node.js for wavedrom - - uses: actions/cache@v3 - with: - path: ~/.npm - key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }} - restore-keys: | - ${{ runner.os }}-node- - - name: Setup Node.js - uses: actions/setup-node@v3 - with: - node-version: '16' - - name: Install Node.js dependencies - run: npm install ${NPM_PACKAGE_FOLDER} - - name: Generate PDF - run: | - PATH=${PATH}:${BUNDLE_BIN}:$(npm bin) \ - make - - name: Archive PDF result + submodules: 'recursive' + + # Step 2: Pull the latest RISC-V Docs container image + - name: Pull Container + run: docker pull riscvintl/riscv-docs-base-container-image:latest + + # Step 3: Build Files + - name: Build Files + run: make + env: + VERSION: v${{ github.event.inputs.version }} + REVMARK: ${{ github.event.inputs.revision_mark }} + + # Step 4: Upload the built PDF files as a single artifact + - name: Upload Build Artifacts uses: actions/upload-artifact@v3 with: - name: ${{ env.NAME }}.pdf - path: ${{ env.NAME }}.pdf - retention-days: 7 + name: Build Artifacts + path: ${{ github.workspace }}/*.pdf + retention-days: 30 + + # Create Release + - name: Create Release + uses: softprops/action-gh-release@v1 + with: + files: ${{ github.workspace }}/*.pdf + tag_name: v${{ github.event.inputs.version }} + name: Release ${{ github.event.inputs.version }} + draft: ${{ github.event.inputs.draft }} + prerelease: ${{ github.event.inputs.prerelease }} + env: + GITHUB_TOKEN: ${{ secrets.GHTOKEN }} + if: github.event_name == 'workflow_dispatch' + # This condition ensures this step only runs for workflow_dispatch events. diff --git a/.github/workflows/create-release.yml b/.github/workflows/create-release.yml deleted file mode 100644 index 014c0e5..0000000 --- a/.github/workflows/create-release.yml +++ /dev/null @@ -1,43 +0,0 @@ -# This work flow includes source and PDF in Release. It relies on the build-pdf workflow to create the PDF. -# -# NOTE: At this time it only runs manually. - -name: Create Document Release - -on: - workflow_dispatch: - inputs: - version: - description: 'Release version, e.g. X.Y.Z:' - required: true - type: string - prerelease: - description: 'Tag as a pre-release?' - required: false - type: boolean - default: true - draft: - description: 'Create release as a draft?' - required: false - type: boolean - default: false - -jobs: - build: - uses: ./.github/workflows/build-pdf.yml - release: - runs-on: ubuntu-latest - needs: build - steps: - - name: Download Artifacts - uses: actions/download-artifact@v3 - with: - name: ${{ needs.build.outputs.pdf-name }} - - name: Create Release - uses: softprops/action-gh-release@v1 - with: - files: ${{ needs.build.outputs.pdf-name }} - tag_name: v${{ github.event.inputs.version }} - name: Release ${{ github.event.inputs.version }} - draft: ${{ github.event.inputs.draft }} - prerelease: ${{ github.event.inputs.prerelease }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ab2007c..3c79557 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,26 +1,23 @@ # Contribution Guidelines -As an open-source project, we welcome and encourage the community to submit patches directly to the project. In our collaborative open source environment, standards and methods for submitting changes help reduce the chaos that can result from an active development community. +As an open-source project, we appreciate and encourage community members to submit patches directly to the project. To maintain a well-organized development environment, we have established standards and methods for submitting changes. This document outlines the process for submitting patches to the project, ensuring that your contribution is swiftly incorporated into the codebase. -This document explains how to submit patches to the project so your patch will be accepted quickly in the codebase. +# Licensing -## Licensing +Licensing is crucial for open-source projects, as it guarantees that the software remains available under the conditions specified by the author. -Licensing is very important to open source projects. It helps ensure the software continues to be available under the terms that the author desired. +This project employs the Creative Commons Attribution 4.0 International license, which can be found in the LICENSE file within the project's repository. -This project uses the Creative Commons Attribution 4.0 International license, as found in the [LICENSE](https://github.com/riscv/docs-spec-template/blob/main/LICENSE) file in the project's repo. +Licensing defines the rights granted to you as an author by the copyright holder. It is essential for contributors to fully understand and accept these licensing rights. In some cases, the copyright holder may not be the contributor, such as when the contributor is working on behalf of a company. -A license tells you what rights you have as an author, as provided by the copyright holder. It is important that the contributor fully understands the licensing rights and agrees to them. Sometimes the copyright holder isn't the contributor, such as when the contributor is doing work on behalf of a company. +# Developer Certificate of Origin (DCO) +To uphold licensing criteria and demonstrate good faith, this project mandates adherence to the Developer Certificate of Origin (DCO) process. -## Developer Certification of Origin (DCO) +The DCO is an attestation appended to every contribution from each author. In the commit message of the contribution (explained in greater detail later in this document), the author adds a Signed-off-by statement, thereby accepting the DCO. -To make a good faith effort to ensure licensing criteria are met, this project requires the Developer Certificate of Origin (DCO) process to be followed. +When an author submits a patch, they affirm that they possess the right to submit the patch under the designated license. The DCO agreement is displayed below and at https://developercertificate.org. -The DCO is an attestation attached to every contribution made by every author. In the commit message of the contribution (described more fully later in this document), the author simply adds a ``Signed-off-by`` statement and thereby agrees to the DCO. -When an author submits a patch, it is a commitment that the contributor has the right to submit the patch per the license. The DCO agreement is shown below and at https://developercertificate.org. - -``` Developer's Certificate of Origin 1.1 By making a contribution to this project, I certify that: @@ -38,7 +35,7 @@ By making a contribution to this project, I certify that: in the file; or (c) The contribution was provided directly to me by some other - person who certified (a), (b) or (c) and I have not modified + person who certified (a), (b), or (c), and I have not modified it. (d) I understand and agree that this project and the contribution @@ -46,19 +43,16 @@ By making a contribution to this project, I certify that: personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved. -``` - -### DCO Sign-Off Methods - -The DCO requires that a sign-off message, in the following format, appears on each commit in the pull request: -`Signed-off-by: Stephano Cetola ` +# DCO Sign-Off Methods +The DCO necessitates the inclusion of a sign-off message in the following format for each commit within the pull request: -You are required to use your real name in the sign-off message. +Signed-off-by: Stephano Cetola -The DCO text can either be manually added to your commit body, or you can add either ``-s`` or ``--signoff`` to your usual Git commit commands. If you forget to add the sign-off you can also amend a previous commit with the sign-off by running ``git commit --amend -s``. If you've pushed your changes to GitHub already you'll need to force push your branch after this with ``git push -f``. +Please use your real name in the sign-off message. +You can manually add the DCO text to your commit body or include either -s or --signoff in your standard Git commit commands. If you forget to incorporate the sign-off, you can also amend a previous commit with the sign-off by executing git commit --amend -s. If you have already pushed your changes to GitHub, you will need to force push your branch afterward using git push -f. -**Note:** +Note: -The name and email address of the account you use to submit your PR must match the name and email address on the ``Signed-off-by`` line in your commit message. +Ensure that the name and email address associated with your GitHub account match the name and email address in the Signed-off-by line of your commit message. \ No newline at end of file diff --git a/Makefile b/Makefile index e6f515d..a46d659 100644 --- a/Makefile +++ b/Makefile @@ -1,21 +1,65 @@ +# Makefile for RISC-V Doc Template +# +# This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 +# International License. To view a copy of this license, visit +# http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to +# Creative Commons, PO Box 1866, Mountain View, CA 94042, USA. +# +# SPDX-License-Identifier: CC-BY-SA-4.0 +# +# Description: +# +# This Makefile is designed to automate the process of building and packaging +# the Doc Template for RISC-V Extensions. + +DATE ?= $(shell date +%Y-%m-%d) +VERSION ?= v0.0.0 +REVMARK ?= Draft +DOCKER_RUN := docker run --rm -v ${PWD}:/build -w /build \ +riscvintl/riscv-docs-base-container-image:latest + HEADER_SOURCE := header.adoc -PDF_RESULT := example-spec.pdf +PDF_RESULT := spec-sample.pdf + +ASCIIDOCTOR_PDF := asciidoctor-pdf +OPTIONS := --trace \ + -a compress \ + -a mathematical-format=svg \ + -a revnumber=${VERSION} \ + -a revremark=${REVMARK} \ + -a revdate=${DATE} \ + -a pdf-fontsdir=docs-resources/fonts \ + -a pdf-theme=docs-resources/themes/riscv-pdf.yml \ + --failure-level=ERROR +REQUIRES := --require=asciidoctor-bibtex \ + --require=asciidoctor-diagram \ + --require=asciidoctor-mathematical + +.PHONY: all build clean build-container build-no-container all: build -build: +build: + @echo "Checking if Docker is available..." + @if command -v docker >/dev/null 2>&1 ; then \ + echo "Docker is available, building inside Docker container..."; \ + $(MAKE) build-container; \ + else \ + echo "Docker is not available, building without Docker..."; \ + $(MAKE) build-no-container; \ + fi + +build-container: + @echo "Starting build inside Docker container..." + $(DOCKER_RUN) /bin/sh -c "$(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE)" + @echo "Build completed successfully inside Docker container." - @echo "Building asciidoc" - asciidoctor-pdf \ - --attribute=mathematical-format=svg \ - --attribute=pdf-fontsdir=docs-resources/fonts \ - --attribute=pdf-style=docs-resources/themes/riscv-pdf.yml \ - --failure-level=ERROR \ - --require=asciidoctor-bibtex \ - --require=asciidoctor-diagram \ - --require=asciidoctor-mathematical \ - --out-file=$(PDF_RESULT) \ - $(HEADER_SOURCE) +build-no-container: + @echo "Starting build..." + $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) --out-file=$(PDF_RESULT) $(HEADER_SOURCE) + @echo "Build completed successfully." clean: - rm $(PDF_RESULT) + @echo "Cleaning up generated files..." + rm -f $(PDF_RESULT) + @echo "Cleanup completed." diff --git a/dependencies/README.md b/dependencies/README.md index 0841ce8..f64a366 100644 --- a/dependencies/README.md +++ b/dependencies/README.md @@ -1,3 +1,2 @@ Dependencies for the build environment for various package managers. Used in `.github/workflows/`. - diff --git a/dependencies/apt_packages.txt b/dependencies/apt_packages.txt index bdf2ce0..6ddd571 100644 --- a/dependencies/apt_packages.txt +++ b/dependencies/apt_packages.txt @@ -1,20 +1,31 @@ bison build-essential +python3-pip cmake curl flex fonts-lyx git graphviz -# For wavedrom default-jre libcairo2-dev libffi-dev libgdk-pixbuf2.0-dev libpango1.0-dev libxml2-dev +libglib2.0-dev make pkg-config ruby ruby-dev +libgif-dev libwebp-dev +libzstd-dev +ruby-full +gem +npm +texlive-latex-base +texlive-fonts-recommended +texlive-fonts-extra +texlive-latex-extra +texlive-science diff --git a/dependencies/package.json b/dependencies/package.json index 9d80afe..7347d43 100644 --- a/dependencies/package.json +++ b/dependencies/package.json @@ -1,7 +1,8 @@ { - "name": "local", - "version": "0.0.1", "dependencies": { + "bytefield-svg": "^1.8.0", "wavedrom-cli": "^2.6.8" - } + }, + "name": "local", + "version": "0.0.1" } diff --git a/example.bib b/example.bib index dd4ca0b..9da24b1 100644 --- a/example.bib +++ b/example.bib @@ -2,39 +2,35 @@ @inproceedings{riscI-isca1981 title = {{RISC I}: {A} Reduced Instruction Set {VLSI} Computer}, author = {David A. Patterson and Carlo H. S\'{e}quin}, booktitle = {ISCA}, - location = {Minneapolis, Minnesota, USA}, + location = {Minneapolis, Minnesota, USA}, pages = {443-458}, year = {1981} } -@InProceedings{Katevenis:1983, - author = {Katevenis, Manolis G.H. and Sherburne,Jr., Robert W. and Patterson, David A. and S{\'e}quin, Carlo H.}, - title = {The {RISC II} micro-architecture}, +@inproceedings{Katevenis:1983, + author = {Manolis G.H. Katevenis and Robert W. Sherburne Jr. and David A. Patterson and Carlo H. S\'{e}quin}, + title = {The {RISC II} micro-architecture}, booktitle = {Proceedings VLSI 83 Conference}, - year = 1983, - month = {August}} + year = {1983}, + month = {August} +} @inproceedings{Ungar:1984, - author = {David Ungar and Ricki Blau and Peter Foley and Dain Samples - and David Patterson}, - title = {Architecture of {SOAR}: {Smalltalk} on a {RISC}}, - booktitle = {ISCA}, - address = {Ann Arbor, MI}, - year = {1984}, - pages = {188--197} -} + author = {David Ungar and Ricki Blau and Peter Foley and Dain Samples and David Patterson}, + title = {Architecture of {SOAR}: {Smalltalk} on a {RISC}}, + booktitle = {ISCA}, + address = {Ann Arbor, MI}, + year = {1984}, + pages = {188-197} +} -@Article{spur-jsscc1989, - author = {David D. Lee and Shing I. Kong and Mark D. Hill and - George S. Taylor and David A. Hodges and Randy - H. Katz and David A. Patterson}, - title = {A {VLSI} Chip Set for a Multiprocessor - Workstation--{Part I}: An {RISC} Microprocessor with - Coprocessor Interface and Support for Symbolic - Processing}, - journal = {IEEE JSSC}, - year = 1989, - volume = 24, - number = 6, - pages = {1688--1698}, - month = {December}} +@article{spur-jsscc1989, + author = {David D. Lee and Shing I. Kong and Mark D. Hill and George S. Taylor and David A. Hodges and Randy H. Katz and David A. Patterson}, + title = {A {VLSI} Chip Set for a Multiprocessor Workstation--{Part I}: An {RISC} Microprocessor with Coprocessor Interface and Support for Symbolic Processing}, + journal = {IEEE JSSC}, + year = {1989}, + volume = {24}, + number = {6}, + pages = {1688-1698}, + month = {December} +} \ No newline at end of file diff --git a/header.adoc b/header.adoc index 3f06ee1..662789d 100644 --- a/header.adoc +++ b/header.adoc @@ -1,22 +1,24 @@ -[[header]] += RISC-V Example Specification Document (Zexmpl) +Authors: Author 1, Author 2 +:docgroup: RISC-V Task Group :description: RISC-V Example Specification Document (Zexmpl) :company: RISC-V.org -:revdate: 1/2022 +:revdate: 1/2023 :revnumber: 1.0 -:revremark: This document is in development. Assume everything can change. See http://riscv.org/spec-state for details. +:revremark: This document is under development. Expect potential changes. Visit http://riscv.org/spec-state for further details. +:revinfo: :url-riscv: http://riscv.org :doctype: book :preface-title: Preamble :colophon: :appendix-caption: Appendix -:imagesdir: images -:title-logo-image: image:risc-v_logo.svg[pdfwidth=3.25in,align=center] +:imagesdir: docs-resources/images +:title-logo-image: image:risc-v_logo.png[pdfwidth=3.25in,align=center] // Settings: :experimental: :reproducible: -// needs to be changed? bug discussion started //:WaveDromEditorApp: app/wavedrom-editor.app -:imagesoutdir: images +:imagesoutdir: docs-resources/images :bibtex-file: example.bib :bibtex-order: alphabetical :bibtex-style: apa @@ -36,16 +38,12 @@ endif::[] :footnote: :xrefstyle: short -= RISC-V Example Specification Document (Zexmpl) -Author 1; Author 2; RISC-V Task Group - -// Preamble [WARNING] .This document is in the link:http://riscv.org/spec-state[Development state] ==== -Assume everything can change. This draft specification will change before -being accepted as standard, so implementations made to this draft -specification will likely not conform to the future standard. +Expect potential changes. This draft specification is likely to evolve before +it is accepted as a standard. Implementations based on this draft +may not conform to the future standard. ==== [preface] @@ -55,13 +53,14 @@ Attribution 4.0 International License (CC-BY 4.0). The full license text is available at https://creativecommons.org/licenses/by/4.0/. -Copyright 2022 by RISC-V International. +Copyright 2023 by RISC-V International. [preface] include::contributors.adoc[] include::intro.adoc[] include::chapter2.adoc[] -//the index must precede the bibliography + +// The index must precede the bibliography include::index.adoc[] include::bibliography.adoc[] diff --git a/images/risc-v_logo.png b/images/risc-v_logo.png new file mode 100755 index 0000000..4e826b2 Binary files /dev/null and b/images/risc-v_logo.png differ diff --git a/images/risc-v_logo.svg b/images/risc-v_logo.svg deleted file mode 120000 index 31e4a40..0000000 --- a/images/risc-v_logo.svg +++ /dev/null @@ -1 +0,0 @@ -../docs-resources/images/risc-v_logo.svg \ No newline at end of file diff --git a/readme.adoc b/readme.adoc index e90f06d..dbc4538 100644 --- a/readme.adoc +++ b/readme.adoc @@ -1,53 +1,110 @@ -= RISC-V docs-spec-template += RISC-V Specification Template -This repository is used to prime GitHub repos for the RISC-V organization which will be used -to create specifications. +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. -**If you are reading this in a specification repo, please update the title for this section and -provide your introduction to your repository.** +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. -= License +== License -This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0). -See the link:LICENSE[LICENSE] file for details. +This work is licensed under a Creative Commons Attribution 4.0 International License (CC-BY-4.0). For details, see the link:LICENSE[LICENSE] file. -= Contributors +== Contributors -Contributors to this specification are contained in the link:contributors.adoc[contributors] file. +The list of contributors to this specification is maintained in the link:contributors.adoc[contributors] file. -For instructions on how to contribute please see the link:CONTRIBUTING.md[CONTRIBUTING] file. +For guidelines on how to contribute, refer to the link:CONTRIBUTING.md[CONTRIBUTING] file. -= Dependencies +== Building the Document -This project is built using AsciiDoctor (Ruby). The repository has been setup to build the PDF on -checkin using GitHub actions. Workflow dependencies are located in the `dependencies` directory. +=== Prerequisites -For more information on AsciiDoctor, specification guidelines, or building locally, see the -https://github.com/riscv/docs-dev-guide[RISC-V Documentation Developer Guide]. +To build the document, you'll need the following tools installed on your system: -= Cloning the project +* Make +* asciiDoctor-pdf, asciidoctor-bibtex, asciidoctor-diagram and asciidoctor-mathematical +* Docker -This project uses https://git-scm.com/book/en/v2/Git-Tools-Submodules[GitHub Submodules] -to include the https://github.com/riscv/docs-resources[RISC-V docs-resources project] -to achieve a common look and feel. +=== Cloning the Repository -When cloning this repository for the first time, you must either use -`git clone --recurse-submodules` or execute `git submodule init` and `git submodule update` after the clone to populate the docs-resources directory. Failure to clone the submodule, will result -in the PDF build fail with an error message like the following: +`git clone --recurse-submodules https://github.com/riscv/docs-spec-template.git` - $ make - asciidoctor-pdf \ - -a toc \ - -a compress \ - -a pdf-style=docs-resources/themes/riscv-pdf.yml \ - -a pdf-fontsdir=docs-resources/fonts \ - --failure-level=ERROR \ - -o profiles.pdf profiles.adoc - asciidoctor: ERROR: could not locate or load the built-in pdf theme `docs-resources/themes/riscv-pdf.yml'; reverting to default theme - No such file or directory - notoserif-regular-subset.ttf not found in docs-resources/fonts - Use --trace for backtrace - make: *** [Makefile:7: profiles.pdf] Error 1 +=== Versioning, Customization and Makefile Variables -= Building the document +This section provides an overview of the environment variables used in our Makefile. These variables include DATE, VERSION, and REVMARK. -The final specification form of PDF can be generated using the `make` command. +* `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 +``` + +=== Building the Documentation + +To start the build process, run `cd ./docs-spec-template && make build`. + +The Makefile script will check the availability of Docker on your system: + +* If Docker is available, the documentation will be built inside a Docker container using the image riscvintl/riscv-docs-base-container-image:latest. This ensures a consistent build environment across different systems. +* If Docker is not available, the documentation will be built directly on your system using the installed tools. + +The documentation is generated from the AsciiDoctor source files in your project. The primary source file is specified by the `HEADER_SOURCE` variable in the Makefile. + +The build process utilizes several options, including theming and font settings, and generates a PDF document as output. + +=== Cleaning up + +To clean up the generated files, run `make clean`. This will remove the generated PDF file.