Contributing Guideline

Thank you for your interest in the RISC-V Architecture Adaptation Knowledge Base. We strongly encourage your participation in the construction of this knowledge base, assisting in providing information about the RISC-V architecture for more developers and contributing to the open-source ecosystem of RISC-V.

Before You Begin

Before making a contribution to this knowledge base, please reach out to the maintenance team through issues, email, or any other means to discuss the changes you intend to make.

Also, make sure to read this contribution guideline and adhere to it while modifying the content of this knowledge base.

Contribution Process

If you wish to suggest ideas or improvements for existing content in the knowledge base, please directly submit Issues.

If you want to make changes or add new content to the existing knowledge base, follow these steps:

1. Fork this repository on Gitee.
2. Read README.md and this document to understand the structure and contribution guidelines of the knowledge base.
3. Find or create the corresponding Markdown document in the docs directory and write the content accordingly.
4. If you want to preview the modified knowledge base locally, install Node.js, run npm install in the project's root directory to install dependencies, and then run npm run docs:dev. This will show you the local preview address.
5. Create a commit and submit it using Git tools, ensuring to mention the modifications in the commit message (refer to Commit Guidelines).
6. Submit a Pull Request to the main project of the knowledge base and wait for the review by the knowledge base maintenance team.
7. If the review is successful, your changes will be credited and merged into the knowledge base. Otherwise, kindly make the necessary modifications and resubmit.

Issue Guidelines

You can submit an Issue on the Gitee repository of the knowledge base to express your opinions or provide suggestions.

Issue submission link: https://gitee.com/rvsmart-porting/knowledge-base/issues

We have prepared an Issue template that you can see when creating a new Issue. Please read the Issue template content and fill it out as required. Make sure to add appropriate labels according to the issue category before submission.

Commit Guidelines

After forking this knowledge base, the changes you make need to be submitted as commits through Git version control. Here are some guidelines regarding commits.

Control the Number of Modifications in a Single Commit

Since a commit contains differences from the previous version, we recommend not making too many modifications at once.

• Do not exceed 5 pages (Markdown files) in a single commit unless they are strongly related pages.
• If there are extensive changes to internal links within a page, place them in a separate commit and check their validity thoroughly.

Write Clear and Concise Commit Messages

When making a commit, you will be asked to provide a commit message. The first line of the commit message will be displayed in the commit history. Only describe the most significant changes, for example:

Fix errors related to GCC in the compilation configuration Supplement content in the section about integer constants in bitwise operations

From the second line of the commit message onwards, we expect you to succinctly explain the changes made in this commit, such as:

• Add 5 compilation parameters and their descriptions related to the floating-point operation features of the RISC-V architecture.
• Add 2 sets of example analyses of macro definitions related to the X86 architecture.

Pull Request Guidelines

When submitting a Pull Request for the changes you made to the knowledge base, please read the template content provided on the Pull Request page and fill in the necessary information. Clearly list all the sections modified in this Pull Request and provide a brief explanation of the changes.

After the knowledge base maintenance team confirms the content of the Pull Request, it will be merged into the main version.

Markdown Format

This knowledge base requires the use of MarkdownLint for Markdown format checks. For detailed check configurations, refer to the .markdownlint.json file in the project's root directory.

The main adjusted rules include:

• MD013 (Line Length): The single line text length limit has been adjusted from the default 80 characters to 120 characters.
• MD025 (Multiple top-level headings in the same document): The Frontmatter check in this rule has been disabled.
• MD033 (Inline HTML): Please refer to the .markdownlint.json configuration file for the currently allowed tags in this rule.

External Link Placeholders

If, in your documentation, some external links cannot be provided temporarily and to pass the MarkdownLint check, please uniformly use https://todo as a placeholder link.

For example:

[This is a placeholder link](https://todo)