Guide to Pull Requests and Issues

Introduction

This guide outlines when to create a Pull Request (PR) and when to create an Issue within our Docusaurus-powered documentation repository. Understanding the difference and knowing the appropriate use cases for each will help maintain an efficient workflow and improve collaboration among contributors.

Pull Request (PR)

A Pull Request (PR) is used to propose changes to the documentation. It allows other contributors to review, discuss, and merge updates. Here are specific scenarios when you should create a PR:

When to Create a PR

1. Adding or Updating Content:

   • Creating new documentation pages.
   • Updating existing documentation with new information or corrections.
   • Enhancing examples or tutorials.

2. Fixing Errors:

   • Correcting typos, grammatical errors, or formatting issues.
   • Fixing broken links or images.

3. Improving Documentation Structure:

   • Restructuring the documentation for better navigation and readability.
   • Updating the sidebar or navbar configuration in Docusaurus.

4. Adding New Features:

   • Introducing new components or plugins to enhance the documentation.
   • Updating the Docusaurus configuration for new functionalities.

5. Styling and Theming:

   • Modifying CSS or themes to improve the visual appearance of the documentation.
   • Implementing responsive design improvements.

Using the PR Template

When creating a PR, please use the provided PR template. This template ensures that all necessary information is included, such as the purpose of the changes and the affected areas. Properly filling out the PR template helps reviewers understand the context and scope of your changes, facilitating a smoother review process.

---

Issue

An Issue is used to report problems, suggest enhancements, or ask questions. It allows the DevEx team to track and discuss these topics. Here are specific scenarios when you should create an Issue:

When to Create an Issue

1. Reporting Bugs:

   • Documenting errors or issues encountered in the existing documentation.
   • Reporting broken links or images that need fixing.

2. Requesting New Content:

   • Suggesting new topics or areas that need to be covered.
   • Requesting additional examples or tutorials.

3. Proposing Enhancements:

   • Suggesting improvements to the documentation structure or organization.
   • Recommending new features or plugins for the documentation site.

4. Asking Questions:

   • Seeking clarification on specific documentation topics.
   • Inquiring about best practices for using the documentation.

Using the Issue Template

When creating an Issue, please use the provided Issue template. This template ensures that all necessary information is included, such as a detailed description of the problem or suggestion. Properly filling out the Issue template helps others understand and address your concerns more effectively.