About

• Version: 1.4

• Creation date: 2020-10-23

• One line description: This document describes the use of RISC-V’s GitHub organization.

• Author(s): Stephano Cetola, Arun Thomas

Background

This document will cover the use of GitHub repositories for RISC-V. The goal is to work on specifications in a unified way and to promote collaboration and an “upstream first” mentality for all software and firmware development.

Details

General Repo Guidelines

• All RISC-V repositories will be created by RISC-V Staff.  To request a new repo, send an email to help@riscv.org with information about the project such as the expected contents, i.e. meeting documents, specification, code, etc.

  • The TPMs will create the repo with standard files such as a README.md, a LICENSE (always on open source license per RISC-V guidelines), and other files based on the project type.  For example, the docs-spec-template (riscv template repo) is used for specifications and template-group-admin (riscv-admin template repo) for groups.

  • The repo location may be one of several RISC-V GitHub organization based on the content.  See the RISC-V TECH wiki GitHub Repo Map page.

  • The repo Administrators will default to Chair and Vice-chair of the group.  This enables the group’s leadership to assign additional roles as needed for administrators and maintainers. However, leadership should only grant special privileges to contributors who are RISC-V members.  Membership verification can be addressed through RISC-V Staff and help@riscv.org.

• All artifacts included in the repo are provided under the repo LICENSE file.  As such, no proprietary code is allowed in a RISC-V GitHub organization repo.

• We try to avoid code binary files, however if it is necessary, code binaries must be accompanied by their source code and that code must be licensed by an OSI approved license.

• Every repository should be public. Private repos require approval of a ISA Committee (IC) or Horizontal Committee (HC).

• The best practices for the repo README file:

  • Describes what the purpose of the project is from an end user perspective. If there are numerous use cases, give some examples. Think about this as describing how this repo fits into the RISC-V ecosystem to a person who does not already have a working knowledge of the project.

  • Defines acronyms on first use.

  • Links to documentation in the repo if available.

  • Provides a contact email (contact help@riscv.org if you need an alias setup).

  • If applicable, provides brief build instructions or usage examples of how to get something meaningful out of the repo. This might be as simple as a script for building the PDF of a specification or a list of requirements for building a binary.

  • For specification repos, provide insight into the current state of the document and directions on how to obtain it.

• Every repository must contain a LICENSE file.  It should:

  • Be CC-BY-4.0 License for RISCV specifications

  • Use a permissive license for software/firmware. Apache 2.0 or BSD 2-clause are preferred and an OSI approved license is required as specified by the RISC-V International License page.

  • Follow the license of the upstream repository for code which has an upstream repository (e.g. GCC, LLVM, OpenJDK, etc.)

  • Be licensed by Apache 2.0 or BSD 2-clause for example code within a specification.

  • When possible, use SPDX headers.

• Every repository should detail the contribution process, either in a CONTRIBUTING file or the README.  This information should:

  • For RISC-V specifications: State that one must be a member to contribute and provide a pointer to the RISC-V Membership webpage.

  • Describe the patch submission and code review process, i.e. whether GitHub Pull Requests, Issues, mailing lists, or any other tools or test (lint scripts) are used and in what order.

  • Articulate whether a  Contributor License Agreement (CLA) or Developer Certification of Origin (DCO) are required.

  • Reference coding style guidelines used by the community.

• To help maintain code quality and prevent accidental changes, please make sure your repository’s main branch is protected with required pull requests before merging. This action ensures that every change is reviewed, tested, and approved before becoming part of production.

• Every repository should contain a list of the maintainers, either in the README or a MAINTAINERS file.

  • List at least two maintainers for the repository. For specifications this is the chair and the co-chair of the task group. For non-specification repositories there should be at least 2 maintainers listed who have admin (push) rights to the repository. Even graduated groups or extensions need two maintainers who have time and are committed to respond.

  • Maintainers must make sure issues have a timely response or delegation upon submission (preferably within a couple working days) and continue to make progress at regular intervals in a timely fashion, preferable within 1-2 working days. 

  • This can be done in the README or in a separate file.

RISC-V Administrative Repos

• Every Task Group must store their charter in a GitHub Repository

  • If there are multiple repositories for the Task Group they can choose the appropriate one themselves or create one specifically for the charter, meeting minutes, and general discussions.

  • The charter can be part of a README document or simply its own file.

  • Once there is a list (perhaps on the wiki) of all the charters, it is the responsibility of the Task Group chair to keep their charter link up to date. This document will be amended with a link to all the charters once available.

• Every Task Group, SIG, and Committee must store meeting minutes in a GitHub repo

  • Please store minutes by date

RISC-V Specifications Repos

• Upon ratification:

  • A git tag should be created whose name is the version number of the release.

  • A GitHub release should be created with the version number of the ratified document. It must contain the source code in tar.gz or zip format of that release and the compiled PDF document.

• For specifications, the only users allowed push rights to the repository are the Chair and Co-Chair of the Task Group.

• Issues should be tracked using GitHub’s issue tracker.

• Code must be committed using a pull request unless the code is pushed directly by the Chair or Co-Chair and is their own work.

• A nightly build should be run using a GitHub action and the PDF artifact and (tar.gz or zip) source code be made publicly available. Nightly builds need only be run if the repo changed.

• All commits should use the Developer Certification of Origin (DCO) signoff process when commiting code (see git-commit -s).

Software and Firmware Repos

• We prefer to do work in upstream repositories rather than development forks if possible.

• We prefer that all software developed by RISC-V International member organizations which is meant to be open source be open as early as possible in the development lifecycle. This reduces duplication of efforts and allows for a more open and collaborative software ecosystem.

• Corporate policies will often require that work be done internally before changes are approved for publication in open source repositories. If this is the case, please work with the Software Horizontal Committee (HC) to ensure that duplication of efforts is minimized or completely avoided if possible.

• Forking Upstream for Development (Staging Upstream Repositories)

  • Early software work for spec or ecosystem enablement can be done as a fork under RISC-V, but these forks must be approved by the Software HC.

  • Approved forks must have a working branch for each feature / bug fix. No work should be done on the main repository branch.

  • Approved forks must follow the development model of the upstream repository. Generally, these upstream repos will have a CONTRIBUTING file or documentation on how to properly upstreamed code.

    • As an example, do not squash 50 commits from different authors into 1 giant commit if that upstream repo works off small incremental changes.

Version History