chore: instructions for new contributors #125
Conversation
WalkthroughThe contribution guide has been enhanced by adding a detailed Development Setup section. This update outlines the necessary tools such as the Rust and C/C++ compilers, Emscripten, Node.js, Yarn, and Tree-Sitter CLI. It also includes instructions for cloning the repository, setting up submodules, and running tests, aiming to streamline the process for new contributors. Changes
Assessment against linked issues
Poem
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (invoked as PR comments)
Additionally, you can add CodeRabbit Configration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
Review Status
Configuration used: CodeRabbit UI
Files selected for processing (1)
- CONTRIBUTING.md (1 hunks)
Additional Context Used
Additional comments not posted (1)
CONTRIBUTING.md (1)
25-39: The instructions for building the code are clear and concise. However, it might be beneficial for contributors if you also include a brief explanation of what each command does. This can help new contributors understand the purpose behind the steps they are taking.
CONTRIBUTING.md
Outdated
| A high level overview of tools you need to have installed: | ||
|
|
||
| * Rust compiler. You'll need [`rustc`](https://rustup.rs/) v1.74 or newer. | ||
| * C/C++ compiler. macOS: [Xcode Command Line Tools](https://download.developer.apple.com/Developer_Tools/Command_Line_Tools_for_Xcode_15.3/Command_Line_Tools_for_Xcode_15.3.dmg) via `xcode-select --install`, Linux: [gcc](https://learnubuntu.com/install-gcc/), Windows: [Microsoft Visual C++](https://visualstudio.microsoft.com/vs/features/cplusplus/). | ||
| * Emscripten: a C/C++ compiler toolchain for WASM. Install v3.1.56 with [`emsdk`](https://emscripten.org/docs/getting_started/downloads.html). | ||
| * Node.js runtime. You'll need [`node`](https://nodejs.org/en/download) v18.5.0 or newer. | ||
| * Yarn package manager. You'll need [`yarn`](https://classic.yarnpkg.com/en/docs/install) (classic). Install v1.22.19 with `npm install --global yarn`. | ||
| * Tree-Sitter CLI: provides [`tree-sitter`](https://github.com/tree-sitter/tree-sitter/tree/master/cli) binary for testing grammars. Install v0.22.2 with `npm install --global tree-sitter-cli`. |
There was a problem hiding this comment.
Consider adding a hyphen to "high level" to form the compound adjective "high-level" as it modifies "overview" in the sentence.
- A high level overview of tools you need to have installed:
+ A high-level overview of tools you need to have installed:Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation.
| A high level overview of tools you need to have installed: | |
| * Rust compiler. You'll need [`rustc`](https://rustup.rs/) v1.74 or newer. | |
| * C/C++ compiler. macOS: [Xcode Command Line Tools](https://download.developer.apple.com/Developer_Tools/Command_Line_Tools_for_Xcode_15.3/Command_Line_Tools_for_Xcode_15.3.dmg) via `xcode-select --install`, Linux: [gcc](https://learnubuntu.com/install-gcc/), Windows: [Microsoft Visual C++](https://visualstudio.microsoft.com/vs/features/cplusplus/). | |
| * Emscripten: a C/C++ compiler toolchain for WASM. Install v3.1.56 with [`emsdk`](https://emscripten.org/docs/getting_started/downloads.html). | |
| * Node.js runtime. You'll need [`node`](https://nodejs.org/en/download) v18.5.0 or newer. | |
| * Yarn package manager. You'll need [`yarn`](https://classic.yarnpkg.com/en/docs/install) (classic). Install v1.22.19 with `npm install --global yarn`. | |
| * Tree-Sitter CLI: provides [`tree-sitter`](https://github.com/tree-sitter/tree-sitter/tree/master/cli) binary for testing grammars. Install v0.22.2 with `npm install --global tree-sitter-cli`. | |
| A high-level overview of tools you need to have installed: | |
| * Rust compiler. You'll need [`rustc`](https://rustup.rs/) v1.74 or newer. | |
| * C/C++ compiler. macOS: [Xcode Command Line Tools](https://download.developer.apple.com/Developer_Tools/Command_Line_Tools_for_Xcode_15.3/Command_Line_Tools_for_Xcode_15.3.dmg) via `xcode-select --install`, Linux: [gcc](https://learnubuntu.com/install-gcc/), Windows: [Microsoft Visual C++](https://visualstudio.microsoft.com/vs/features/cplusplus/). | |
| * Emscripten: a C/C++ compiler toolchain for WASM. Install v3.1.56 with [`emsdk`](https://emscripten.org/docs/getting_started/downloads.html). | |
| * Node.js runtime. You'll need [`node`](https://nodejs.org/en/download) v18.5.0 or newer. | |
| * Yarn package manager. You'll need [`yarn`](https://classic.yarnpkg.com/en/docs/install) (classic). Install v1.22.19 with `npm install --global yarn`. | |
| * Tree-Sitter CLI: provides [`tree-sitter`](https://github.com/tree-sitter/tree-sitter/tree/master/cli) binary for testing grammars. Install v0.22.2 with `npm install --global tree-sitter-cli`. |
CONTRIBUTING.md
Outdated
|
|
||
| A high level overview of tools you need to have installed: | ||
|
|
||
| * Rust compiler. You'll need [`rustc`](https://rustup.rs/) v1.74 or newer. |
There was a problem hiding this comment.
This is redundant from the ## development tools section below - please consolidate.
There was a problem hiding this comment.
Done. Please see dbe396f.
There was a problem hiding this comment.
Actionable comments posted: 2
Review Status
Configuration used: CodeRabbit UI
Files selected for processing (1)
- CONTRIBUTING.md (1 hunks)
Additional Context Used
Additional comments not posted (2)
CONTRIBUTING.md (2)
16-21: Ensure all tool versions mentioned are up-to-date and consider specifying if newer versions are also supported. Additionally, for tools likerustcandnode, it might be helpful to mention how to check the current installed version.
25-39: The build instructions are clear and concise. Consider adding a note about potential issues that contributors might encounter during setup (e.g., submodule permissions, test dependencies) and how to resolve them.
There was a problem hiding this comment.
Actionable comments posted: 2
Review Status
Configuration used: CodeRabbit UI
Files selected for processing (1)
- CONTRIBUTING.md (2 hunks)
Additional Context Used
Additional comments not posted (1)
CONTRIBUTING.md (1)
27-41: Ensure the build instructions are clear and easy to follow for new contributors. Consider adding a brief explanation of what each command does for those unfamiliar with Git or Cargo.
There was a problem hiding this comment.
Actionable comments posted: 1
Review Status
Configuration used: CodeRabbit UI
Files selected for processing (1)
- CONTRIBUTING.md (2 hunks)
Additional Context Used
Additional comments not posted (2)
CONTRIBUTING.md (2)
14-23: The "Development Setup" section provides a comprehensive list of tools required for contributing. However, it's important to ensure that the versions of the tools mentioned are kept up-to-date to avoid potential issues for contributors. Regularly reviewing and updating these versions can help maintain the accuracy of the setup instructions.
16-16: In the "Development Setup" section, the Rust toolchain version is specified as v1.74 or newer. Given the rapid development of Rust, it's crucial to verify that this version remains compatible with the project's codebase and to update the documentation accordingly if newer versions introduce breaking changes.
| ## Building the Code | ||
|
|
||
| Use `git` to clone this repository into a location of your choice. | ||
| ```bash | ||
| git clone https://github.com/getgrit/gritql.git | ||
| ``` | ||
|
|
||
| Change into the cloned repository and make sure all submodules are correctly set up, including any nested submodules: | ||
| ```bash | ||
| cd gritql | ||
| git submodule update --init --recursive | ||
| ``` | ||
|
|
||
| Before making any changes to the code, make sure you can run the tests and everything is initially passing: | ||
| ```bash | ||
| cargo test --workspace | ||
| ``` |
There was a problem hiding this comment.
The "Building the Code" section clearly outlines the steps to clone the repository, set up submodules, and run tests. This is a significant improvement for new contributors. To further enhance this section, consider adding a troubleshooting subsection that addresses common issues encountered during the setup process, such as submodule initialization errors or test failures.
Would you like me to draft a troubleshooting subsection to address common setup issues?
This PR intends to close #44 by adding info to CONTRIBUTING.md on:
Summary by CodeRabbit