Merge pull request #4 from tracel-ai/ci/xtask-and-workflow

Cargo xtask and CI workflows

.cargo/audit.toml

@@ -0,0 +1,10 @@
+# It may be located in the user home (`~/.cargo/audit.toml`) or in the project
+# root (`.cargo/audit.toml`).
+#
+# All of the options which can be passed via CLI arguments can also be
+# permanently specified in this file.
+#
+# See example file at: https://github.com/rustsec/rustsec/blob/main/cargo-audit/audit.toml.example
+
+[advisories]
+ignore = []

.cargo/config.toml

@@ -0,0 +1,2 @@
+[alias]
+xtask = "run --target-dir target/xtask/debug --package xtask --bin xtask --"

.github/workflows/ci.yml

@@ -0,0 +1,70 @@
+name: CI
+
+env:
+  CARGO_TERM_COLOR: always
+
+# For now we execute CI only on PR to save on CI time
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'Cargo.lock'
+      - '**.rs'
+      - '**.yml'
+      - '**.toml'
+      - '!**.md'
+      - '!LICENSE-APACHE'
+      - '!LICENSE-MIT'
+  pull_request:
+    types: [opened, synchronize]
+    paths:
+      - 'Cargo.lock'
+      - '**.rs'
+      - '**.yml'
+      - '**.toml'
+      - '!**.md'
+      - '!LICENSE-APACHE'
+      - '!LICENSE-MIT'
+
+jobs:
+  crates:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          components: clippy, rustfmt
+          toolchain: stable
+      - uses: Swatinem/rust-cache@v2
+      - name: Format
+        run: cargo xtask ci --target crates format
+      - name: Lint
+        run: cargo xtask ci --target crates lint
+      - name: Audit
+        run: cargo xtask ci --target crates audit
+      - name: Unit Tests
+        run: cargo xtask ci --target crates unit-tests
+      - name: Integration Tests
+        run: cargo xtask ci --target crates integration-tests
+      - name: Documentation Tests
+        run: cargo xtask ci --target crates doc-tests
+  examples:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          components: clippy, rustfmt
+          toolchain: stable
+      - uses: Swatinem/rust-cache@v2
+      - name: Format
+        run: cargo xtask ci --target examples format
+      - name: Lint
+        run: cargo xtask ci --target examples lint
+      - name: Unit Tests
+        run: cargo xtask ci --target examples unit-tests
+      - name: Integration Tests
+        run: cargo xtask ci --target examples integration-tests
+      - name: Documentation Tests
+        run: cargo xtask ci --target examples doc-tests

.github/workflows/publish-template.yml

@@ -0,0 +1,24 @@
+on:
+  workflow_call:
+    inputs:
+      crate:
+        required: true
+        type: string
+    secrets:
+      CRATES_IO_API_TOKEN:
+        required: true
+
+jobs:
+  publish-crate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: checkout
+        uses: actions/checkout@v3
+
+      - name: install rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: publish to crates.io
+        run: cargo xtask publish ${{ inputs.crate }}
+        env:
+          CRATES_IO_API_TOKEN: ${{ secrets.CRATES_IO_API_TOKEN }}

.github/workflows/publish.yml

@@ -0,0 +1,46 @@
+name: publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish-cubecl-common:
+    uses: tracel-ai/cubecl/.github/workflows/publish-template.yml@main
+    with:
+      crate: cubecl-common
+    secrets: inherit
+
+  publish-cubecl-runtime:
+    uses: tracel-ai/cubecl/.github/workflows/publish-template.yml@main
+    with:
+      crate: cubecl-runtime
+    needs:
+      - publish-cubecl-common
+    secrets: inherit
+
+  publish-cubecl-macros:
+    uses: tracel-ai/cubecl/.github/workflows/publish-template.yml@main
+    with:
+      crate: cubecl-macros
+    needs:
+      - publish-cubecl-common
+    secrets: inherit
+
+  publish-cubecl-core:
+    uses: tracel-ai/cubecl/.github/workflows/publish-template.yml@main
+    with:
+      crate: cubecl-core
+    needs:
+      - publish-cubecl-runtime
+      - publish-cubecl-macros
+    secrets: inherit
+
+  publish-cubecl:
+    uses: tracel-ai/cubecl/.github/workflows/publish-template.yml@main
+    with:
+      crate: cubecl
+    needs:
+      - publish-cubecl-core
+    secrets: inherit

CONTRIBUTING.md

@@ -0,0 +1,130 @@
+# Contributing to the CubeCL Project
+
+Welcome to the CubeCL project! We're thrilled that you're considering contributing to our project.
+Every contribution helps, and we're delighted to have you on board.
+
+## How to Contribute?
+
+Here are some steps to guide you through the process of contributing to the CubeCL project:
+
+### Step 1: Review the Issue Tickets
+
+Before you start working on a contribution, please take a moment to look through the open issues in
+the [issue tracker][1] for this project. This will give you an
+idea of what kind of work is currently being planned or is in progress.
+
+### Step 2: Get Familiar with the project
+
+Familiarize yourself with the structure of the project, the purpose of different components, and how they
+interact with each other by reading the [README.md][2] file of the repository. This will give you the
+context needed to make meaningful contributions. You can also check the examples in the [examples][3]
+directory in order to see CubeCL in action. It is recommended to get familiar with the `cargo xtask`
+command which provides useful commands to execute checks, tests etc... see the [cargo xtask README][4]
+for more information.
+
+### Step 3: Fork and Clone the Repository
+
+Before you can start making changes, you'll need to fork the CubeCL repository and clone it to your
+local machine. This can be done via the GitHub website or the GitHub Desktop application. Here are
+the steps:
+
+1. Click the "Fork" button at the top-right of this page to create a copy of this project in your
+   GitHub account.
+2. Clone the repository to your local machine. You can do this by clicking the "Code" button on the
+   GitHub website and copying the URL. Then open a terminal on your local machine and type
+   `git clone [the URL you copied]`.
+
+### Step 4: Create a New Branch
+
+It's a good practice to create a new branch for each contribution you make. This keeps your changes
+organized and separated from the main project, which can make the process of reviewing and merging
+your changes easier. You can create a new branch by using the command
+`git checkout -b [branch-name]`.
+
+### Step 5: Make Your Changes
+
+Once you have set up your local repository and created a new branch, you can start making changes.
+Be sure to follow the coding standards and guidelines used in the rest of the project.
+
+### Step 6: Run the Pre-Pull Request Script
+
+Before you open a pull request, please run the following xtask command at the root of the repository:
+
+```sh
+cargo xtask pull-request-checks
+```
+
+This will ensure that your changes are in line with our project's standards and guidelines.
+
+### Step 7: Submit a Pull Request
+
+After you've made your changes and run the xtask command, you're ready to submit a pull request.
+This can be done through the GitHub website or the [GitHub Desktop application][5].
+
+When submitting your pull request, please provide a brief description of the changes you've made and
+the issue or issues that your changes address.
+
+### Optional but recommended step for VS Code developers: Setting up environment
+
+1. Install the following extensions:
+
+- [rust-lang.rust-analyzer](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer)
+- [tamasfe.even-better-toml](https://marketplace.visualstudio.com/items?itemName=tamasfe.even-better-toml)
+- [serayuzgur.crates](https://marketplace.visualstudio.com/items?itemName=serayuzgur.crates)
+- [vadimcn.vscode-lldb](https://marketplace.visualstudio.com/items?itemName=vadimcn.vscode-lldb)
+
+2. Open `Command Palette` with Ctrl+Shift+P or F1 and type `LLDB: Generate Launch Configurations from Cargo.toml`
+   then select it, this will generate a file that should be saved as `.vscode/launch.json`.
+   You may also want to enable debugging by creating a `.vscode/settings.json` file:
+   ```json
+   {
+   "rust-analyzer.runnables.extraEnv": {
+      "CARGO_PROFILE_DEV_DEBUG": true
+   }
+   }
+   ```
+   since this repo has `debug = 0` in the root `Cargo.toml` to speed up compilation.
+
+3. Now you can enable breakpoint on code through IDE and then start debugging the library/binary you want, such as the following example:
+
+<div align="center">
+<img src="./assets/debug-options-vscode.png" width="700px"/>
+<div align="left">
+
+4. If you're creating a new library or binary, keep in mind to repeat the step 2 to always keep a fresh list of targets.
+
+## Code Guidelines
+
+We believe in clean and efficient code. While we don't enforce strict coding guidelines, we trust
+and use tools like `cargo fmt` and `cargo clippy` to maintain code quality. These are integrated
+into our xtask commands, ensuring consistency across our codebase.
+
+### Writing Expect Messages
+
+In Rust, the `expect()` function is a crucial tool for handling errors. However, the power of
+`expect()` lies in its ability to convey clear, actionable messages. When you use `expect()`, your
+message should describe the successful outcome of the function rather than focusing on the error.
+
+Here's a helpful tip from the [Rust documentation][6]:
+
+_Think of `expect()` messages as guidelines for future you and other developers. Frame them with the word “should” like “The ENV variable should be set by X function” or “The binary should be accessible and executable by the current user.”_
+
+This approach ensures that `expect()` messages are informative and aligned with the intended
+function outcomes, making debugging and maintenance more straightforward for everyone.
+
+---
+
+We look forward to seeing your contributions to the CubeCL project. Happy coding!
+
+If you have any questions and would like to get in touch with us, please feel free to join our
+discord server:
+
+[![Discord](https://img.shields.io/discord/1038839012602941528.svg?color=7289da&&logo=discord)][7]
+
+[1]: https://github.com/tracel-ai/cubecl/issues
+[2]: https://github.com/tracel-ai/cubecl/blob/main/README.md
+[3]: https://github.com/tracel-ai/cubecl/tree/main/examples
+[4]: https://github.com/tracel-ai/cubecl/blob/main/xtask/README.md
+[5]: https://desktop.github.com/
+[6]: https://doc.rust-lang.org/std/result/enum.Result.html#recommended-message-style
+[7]: https://discord.gg/uPEBbYYDB6

Cargo.toml

@@ -7,6 +7,7 @@ resolver = "2"
 members = [
     "crates/*",
     "examples/*",
+    "xtask",
 ]
 
 [workspace.package]
@@ -44,6 +45,7 @@ async-channel = "2.3"
 
 # Testing
 serial_test = "3.1.1"
+rstest = "0.19.0"
 
 bytemuck = "1.16.1"
 half = { version = "2.4.1", features = [
@@ -59,5 +61,12 @@ proc-macro2 = "1.0.86"
 syn = { version = "2.0.69", features = ["full", "extra-traits"] }
 quote = "1.0.36"
 
+# xtask
+anyhow = "1.0.86"
+clap = { version = "4.5.9", features = ["derive"] }
+derive_more = { version = "0.99.18", features = ["display"], default-features = false }
+env_logger = "0.11.3"
+strum = {version = "0.26.3", features = ["derive"]}
+
 [profile.dev]
 opt-level = 2

xtask/Cargo.toml

@@ -0,0 +1,19 @@
+[package]
+name = "xtask"
+version = "0.1.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+anyhow = { workspace = true }
+clap = { workspace = true }
+derive_more = { workspace = true }
+env_logger = { workspace = true }
+log = { workspace = true }
+rand = { workspace = true, features = ["std"] }
+serde_json = { version = "1.0.119" }
+strum = { workspace = true }
+
+[dev-dependencies]
+rstest = { workspace = true }