documentation updates (#571)

Author: dhower-qc

.gitmessage

@@ -0,0 +1,29 @@
+# <type>(<scope>): <short summary>
+# No line more than 80 chars. #### 80 chars is here:                          #
+
+# Body: Explain *what* and *why* (not *how*).
+# <put body here>
+
+# Conventional Footer: required if this is a breaking change
+# BREAKING CHANGE: <summary of what breaks>
+#
+# <Breaking change description + migration instructions>
+
+# At the end: Include Co-authored-by if relevant.
+# Co-authored-by: name <user@users.noreply.github.com>
+
+# common title types:
+#   build:    build system
+#   ci:       continous integration
+#   docs:     improves documentation
+#   feat:     adds a new feature
+#   fix:      fixes a code bug
+#   perf:     performance improvement
+#   refactor: changes code, neither a fix nor feature
+#   revert:   reverts a prior commit(s)
+#   style:    style update
+
+# common title scopes:
+#   data:     Database information
+#   schema:   Database schema
+#   ruby:     Ruby code

.pre-commit-config.yaml

@@ -8,47 +8,63 @@ repos:
     rev: v5.0.0
     hooks:
       - id: check-ast
+        stages: [pre-commit]
       - id: check-builtin-literals
+        stages: [pre-commit]
       - id: check-case-conflict
+        stages: [pre-commit]
       - id: check-docstring-first
+        stages: [pre-commit]
       - id: check-symlinks
+        stages: [pre-commit]
       - id: end-of-file-fixer
+        stages: [pre-commit]
       - id: trailing-whitespace
+        stages: [pre-commit]
         args: [--markdown-linebreak-ext=md]
       - id: check-merge-conflict
+        stages: [pre-commit]
         args: ["--assume-in-merge"]
         exclude: \.adoc$ # sections titles Level 6 "=======" get flagged otherwise
       - id: check-json
+        stages: [pre-commit]
         exclude: ^\.devcontainer/ # Uses JSONC (comments)
       - id: check-yaml
+        stages: [pre-commit]
 
   - repo: https://github.com/rbubley/mirrors-prettier
     rev: v3.5.3
     hooks:
       - id: prettier
+        stages: [pre-commit]
         files: \.(json|toml|yml|yaml)$
         exclude: schemas/json-schema-draft-07.json
 
   - repo: https://github.com/python-jsonschema/check-jsonschema
     rev: 0.33.0
     hooks:
       - id: check-jsonschema
+        stages: [pre-commit]
         alias: check-jsonschema-inst
         files: ^arch/inst/.*\.(yaml|yml)$
         args: ["--schemafile", "schemas/inst_schema.json"]
       - id: check-jsonschema
+        stages: [pre-commit]
         alias: check-jsonschema-csr
         files: ^arch/csr/.*\.(yaml|yml)$
         args: ["--schemafile", "schemas/csr_schema.json"]
       - id: check-jsonschema
+        stages: [pre-commit]
         alias: check-jsonschema-ext
         files: ^arch/ext/.*\.(yaml|yml)$
         args: ["--schemafile", "schemas/ext_schema.json"]
       - id: check-jsonschema
+        stages: [pre-commit]
         alias: check-jsonschema-cert-model
         files: ^arch/proc_cert_model/.*\.(yaml|yml)$
         args: ["--schemafile", "schemas/proc_cert_model_schema.json"]
       - id: check-jsonschema
+        stages: [pre-commit]
         alias: check-jsonschema-cert-class
         files: ^arch/proc_cert_class/.*\.(yaml|yml)$
         args: ["--schemafile", "schemas/proc_cert_class_schema.json"]
@@ -62,6 +78,7 @@ repos:
     rev: "v20.1.0"
     hooks:
       - id: clang-format
+        stages: [pre-commit]
         types_or: [c++, c]
         files: \.(hpp|cpp)$
         # TEMPORARILY DISABLE CLANG-FORMAT IN LIBHART
@@ -71,11 +88,13 @@ repos:
     rev: 25.1.0
     hooks:
       - id: black
+        stages: [pre-commit]
 
   - repo: https://github.com/asottile/pyupgrade
     rev: v3.19.1
     hooks:
       - id: pyupgrade
+        stages: [pre-commit]
 
   - repo: local
     hooks:
@@ -90,6 +109,7 @@ repos:
     rev: v3.11.0-1
     hooks:
       - id: shfmt
+        stages: [pre-commit]
         args:
           - --indent
           - "2"
@@ -99,3 +119,11 @@ repos:
     rev: v5.0.2
     hooks:
       - id: reuse
+
+  - repo: https://github.com/alessandrojcm/commitlint-pre-commit-hook
+    rev: v9.22.0
+    hooks:
+      - id: commitlint
+        stages: [commit-msg]
+        additional_dependencies:
+          - "@commitlint/config-conventional"

CODE_OF_CONDUCT.adoc

@@ -0,0 +1,57 @@
+= UnifiedDB Code of Conduct
+
+UnifiedDB follows the RISC-V International Code of Conduct.
+
+== Our Pledge
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socioeconomic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+== Our Standards
+Examples of behavior that contributes to creating a positive environment include:
+
+Using welcoming and inclusive language
+Being respectful of differing viewpoints and experiences
+Gracefully accepting constructive criticism
+Focusing on what is best for the community
+Showing empathy towards other community members
+Examples of unacceptable behavior by participants include:
+
+The use of sexualized language or imagery and unwelcome sexual attention or advances
+Trolling, insulting/derogatory comments, and personal or political attacks
+Trafficking in disinformation, unsubstantiated slanderous rumors, and conspiracy theories
+Public or private harassment
+Publishing others' private information, such as a physical or electronic address, without explicit permission
+Other conduct which could reasonably be considered inappropriate in a professional setting
+Our Responsibilities
+RISC-V International is responsible for clarifying the standards of acceptable behavior and is expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.  RISC-V International has the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+== Scope
+This Code of Conduct applies within all project spaces, and it also applies when an individual is representing the project or its community in public spaces. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+== Enforcement
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting RISC-V International at conduct@riscv.org. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. RISC-V International is obligated to maintain confidentiality with regard to the reporter of an incident.
+
+== Enforcement Guidelines
+RISC-V International will follow these guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+=== 1. Correction
+Community Impact:: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+Consequence:: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested. Moderation of postings may be used if applicable.
+
+=== 2. Warning
+Community Impact:: A violation through a single incident or series of actions.
+
+Consequence:: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+=== 3. Temporary Ban
+Community Impact:: A serious violation of community standards, including sustained inappropriate behavior.
+
+Consequence:: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+=== 4. Permanent Ban
+Community Impact:: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+Consequence:: A permanent ban from any sort of public interaction within the community.
+
+== Attribution
+This Code of Conduct is based on the https://www.contributor-covenant.org/version/2/1/code_of_conduct/[Contributor Covenant, version 2.1]. For answers to common questions about this code of conduct, see the Contributor Covenant https://www.contributor-covenant.org/faq[FAQ].

CONTRIBUTING.adoc

@@ -0,0 +1,183 @@
+= UnifiedDB Contribution Guide
+
+Thank you for your interest in contributing to UnifiedDB!
+We welcome all contributions that meet our xref:CODE_OF_CONDUCT.adoc[code of conduct].
+
+== Ways to contribute
+
+=== Bug Reports
+
+Bug reports should be filed as a https://github.com/riscv-software-src/riscv-unified-db/issues[GitHub Issue] using the `Bug report` template.
+
+=== Feature Requests
+
+Bug reports should be filed as a https://github.com/riscv-software-src/riscv-unified-db/issues[GitHub Issue] using the `Feature request` template.
+
+=== Bug Fixes
+
+Bug fixes should be submitted as a Pull Request.
+
+There should be a corresponding https://github.com/riscv-software-src/riscv-unified-db/issues[GitHub Issue] for the PR. Ensure the two are linked by adding "closes #<issue number>" in the PR description.
+
+=== New data, tools, and features
+
+New data (for example, adding an extension), tools, or features should be submitted as a Pull Request.
+
+There should be a corresponding https://github.com/riscv-software-src/riscv-unified-db/issues[GitHub Issue] for the PR. Ensure the two are linked by adding "closes #<issue number>" in the PR description.
+
+== Submitting a Pull Request
+
+All patches must meet the UnifiedDB code standards. This includes:
+
+* Pass regression tests (run locally as `./do test:regress`)
+* Use appropriate commit messages
+* Go through code review as a Pull Request
+
+=== Regression tests
+
+All contributions must pass the full suite of regression tests.
+Regression tests are checked in GitHub for every PR, and they can also be run locally using `./do test:regress`.
+
+If a Pull Request adds a new feature that is not already covered by the regression test suite, it
+must add at least one new test.
+
+=== Commit messages
+
+UnifiedDB adheres to https://www.conventionalcommits.org/en/v1.0.0[Conventional Commits v1.0.0].
+
+The guidelines below are adapted from https://github.com/angular/angular/blob/main/contributing-docs/commit-message-guidelines.md[the Angular commit message guidelines].
+
+Every commit message consists of a mandatory *header*, a mandatory *body*, and an optional *footer*.
+
+```
+<header>
+<BLANK LINE>
+<body>
+<BLANK LINE>
+<footer>
+```
+
+A template for commit messages is stored in xref:.gitmessage[], and will be installed automatically through the standard UnifiedDB setup script so that it appears when executing `git commit`.
+
+==== Header
+
+.UnifiedDB commit header format
+```
+<type>(<scope>): <short summary>
+  │       │             │
+  │       │             └─⫸ Summary in present tense. Not capitalized. No period at the end.
+  │       │
+  │       └─⫸ Optional Commit Scope: single word describing the component
+  │
+  └─⫸ Commit Type: e.g., build|ci|docs|feat|fix|perf|refactor|revert|style|test
+```
+
+The `<type>` and `<summary>` fields are mandatory. The `<scope>` field is optional.
+
+==== Body
+
+Just as in the summary, use the imperative, present tense: "fix" not "fixed" nor "fixes".
+
+Explain the motivation for the change in the commit message body. This commit message should explain
+_why_ you are making the change.
+You can include a comparison of the previous behavior with the new behavior in order to illustrate
+the impact of the change.
+
+==== Footer
+
+A footer is required when the commit introduces a breaking change, closes a GitHub issue,
+or has relevant git trailers.
+
+===== Breaking change
+
+When a commit introduces a breaking change to _any_ component, the commit message *must* include
+a breaking change note in the footer:
+
+```
+BREAKING CHANGE: <breaking change summary>
+<BLANK LINE>
+<breaking change description + migration instructions>
+```
+
+==== Linked Issues and PRs
+
+When a commit will close a GitHub Issue, it should be noted in the footer:
+
+```
+Fixes #<issue number>
+Closes #<issue numer>
+```
+
+==== Git trailers
+
+When any of the extra information is relevant to a commit, it should be marked with a git trailer.
+Standard trailers for UnifiedDB include:
+
+[cols="1,2,3"]
+|===
+| Key | Value format | Description
+| Co-authored-by | Firstname Lastname <email> | A person, other than the committer, that authored part of the patch
+|===
+
+==== Examples
+
+The following are examples of good commit messages:
+
+```
+data(ext): add Smclic extension
+
+Add metadata and IDL for Smclic (Core Local Interrupt Controller) v1.0.
+
+Closes #816
+```
+
+```
+correct(ext): sctrclr belongs to Smctr/Sscntr extensions
+
+The sctrclr instruction was improperly `definedBy` Smdbltrp
+
+Closes #490
+```
+
+```
+feat(ruby-db): add Sorbet type checking
+
+Add Sorbet type signatures to ruby-db code, and run Sorbet type check in CI.
+
+Closes #934
+Co-authored-by: Frank the Tank <frank@oldschool.movie>
+```
+
+=== Code review
+
+All Pull Requests must go through the code review process.
+
+All Pull Requests require approval by at least one Code Owner.
+
+Code Owners are maintained in `.github/CODEOWNERS`.
+
+== Finding tasks
+
+If you are looking to contribute but are unsure what to do, browse through the https://github.com/riscv-software-src/riscv-unified-db/issues[issues]. We try to keep them tagged by area and mark easier tasks with "good first issue".
+
+== Legal
+
+All contributions to UnifiedDB are by default made under the xref:LICENSE[BSD-3-clear license].
+Copyrights are held by the specific contributors, and are not tracked by the UnifiedDB project other
+than what can be gleaned through git history.
+
+Under special circumstances code may be added under a different license.
+For example, code from an existing project may be integrated after careful deliberation.
+Any contributions under a different license will receive extra review.
+When any contribution is made under a different license, it must be tracked using
+https://reuse.software/tutorial/#step-2[a Reuse-compatible identifer].
+
+To keep UnifiedDB open to both private and commercial interests, contributions under a
+https://en.wikipedia.org/wiki/copyleft[copyleft license] will never be accepted.
+
+== Maintainers
+
+The current maintainers for UnifiedDB are:
+
+* Derek Hower (@dhower-qc)
+* Paul Clarke (@ThinkOpenly)