You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opendal.apache.org by ps...@apache.org on 2026/08/10 15:49:54 UTC

(opendal-ofs) branch stack/xtask-tooling created (now 3e78f32)

This is an automated email from the ASF dual-hosted git repository.

PsiACE pushed a change to branch stack/xtask-tooling
in repository https://gitbox.apache.org/repos/asf/opendal-ofs.git


      at 3e78f32  ci: run checks through cargo xtask

This branch includes the following new commits:

     new 7b430f5  build: add cargo xtask tooling
     new cdfbc41  docs: document repository workflows
     new 3e78f32  ci: run checks through cargo xtask

The 3 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.



(opendal-ofs) 01/03: build: add cargo xtask tooling

Posted by ps...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

PsiACE pushed a commit to branch stack/xtask-tooling
in repository https://gitbox.apache.org/repos/asf/opendal-ofs.git

commit 7b430f5ba2940a248e4cfa3b90cf3974c5b4c646
Author: PsiACE <ps...@apache.org>
AuthorDate: Mon Aug 10 23:46:59 2026 +0800

    build: add cargo xtask tooling
---
 rust-toolchain.toml => .cargo/config.toml |   8 +-
 Cargo.lock                                |   4 +
 Cargo.toml                                |  19 ++-
 rust-toolchain.toml                       |   2 +-
 rust-toolchain.toml => xtask/Cargo.toml   |  19 ++-
 xtask/src/main.rs                         | 233 ++++++++++++++++++++++++++++++
 6 files changed, 272 insertions(+), 13 deletions(-)

diff --git a/rust-toolchain.toml b/.cargo/config.toml
similarity index 89%
copy from rust-toolchain.toml
copy to .cargo/config.toml
index 24ee9ce..f86e56b 100644
--- a/rust-toolchain.toml
+++ b/.cargo/config.toml
@@ -15,6 +15,8 @@
 # specific language governing permissions and limitations
 # under the License.
 
-[toolchain]
-channel = "stable"
-components = ["cargo", "rustfmt", "clippy", "rust-analyzer"]
+[alias]
+x = "run --package x --"
+
+[env]
+CARGO_WORKSPACE_DIR = { value = "", relative = true }
diff --git a/Cargo.lock b/Cargo.lock
index 788d2d6..0073e75 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -5,3 +5,7 @@ version = 4
 [[package]]
 name = "ofs"
 version = "0.0.24"
+
+[[package]]
+name = "x"
+version = "0.0.0"
diff --git a/Cargo.toml b/Cargo.toml
index 90f2937..558bcc8 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -23,17 +23,24 @@ name = "ofs"
 version = "0.0.24"
 
 authors = ["Apache OpenDAL <de...@opendal.apache.org>"]
-edition = "2024"
-homepage = "https://opendal.apache.org/"
-license = "Apache-2.0"
+edition.workspace = true
+homepage.workspace = true
+license.workspace = true
 publish = false
-repository = "https://github.com/apache/opendal-ofs"
-rust-version = "1.85"
+repository.workspace = true
+rust-version.workspace = true
 
 [workspace]
-members = ["."]
+members = [".", "xtask"]
 resolver = "3"
 
+[workspace.package]
+edition = "2024"
+homepage = "https://opendal.apache.org/"
+license = "Apache-2.0"
+repository = "https://github.com/apache/opendal-ofs"
+rust-version = "1.85.0"
+
 [workspace.metadata.release]
 pre-release-commit-message = "chore: release v{{version}}"
 shared-version = true
diff --git a/rust-toolchain.toml b/rust-toolchain.toml
index 24ee9ce..fd5d8cb 100644
--- a/rust-toolchain.toml
+++ b/rust-toolchain.toml
@@ -16,5 +16,5 @@
 # under the License.
 
 [toolchain]
-channel = "stable"
+channel = "1.85.0"
 components = ["cargo", "rustfmt", "clippy", "rust-analyzer"]
diff --git a/rust-toolchain.toml b/xtask/Cargo.toml
similarity index 75%
copy from rust-toolchain.toml
copy to xtask/Cargo.toml
index 24ee9ce..5de453a 100644
--- a/rust-toolchain.toml
+++ b/xtask/Cargo.toml
@@ -15,6 +15,19 @@
 # specific language governing permissions and limitations
 # under the License.
 
-[toolchain]
-channel = "stable"
-components = ["cargo", "rustfmt", "clippy", "rust-analyzer"]
+[package]
+name = "x"
+version = "0.0.0"
+
+edition.workspace = true
+homepage.workspace = true
+license.workspace = true
+publish = false
+repository.workspace = true
+rust-version.workspace = true
+
+[package.metadata.release]
+release = false
+
+[lints]
+workspace = true
diff --git a/xtask/src/main.rs b/xtask/src/main.rs
new file mode 100644
index 0000000..81fc25e
--- /dev/null
+++ b/xtask/src/main.rs
@@ -0,0 +1,233 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Repository tasks shared by local development and CI.
+
+use std::env;
+use std::path::Path;
+use std::process::Command;
+use std::process::ExitCode;
+
+type Result<T> = std::result::Result<T, String>;
+
+fn main() -> ExitCode {
+    match run() {
+        Ok(()) => ExitCode::SUCCESS,
+        Err(error) => {
+            eprintln!("error: {error}");
+            ExitCode::FAILURE
+        }
+    }
+}
+
+fn run() -> Result<()> {
+    let mut args = env::args().skip(1);
+    let Some(command) = args.next() else {
+        print_help();
+        return Ok(());
+    };
+
+    match command.as_str() {
+        "check" => run_check(args),
+        "test" => run_test(args),
+        "lint" => run_lint(args),
+        "licenses" => run_licenses(args),
+        "help" | "-h" | "--help" => {
+            ensure_no_args(args)?;
+            print_help();
+            Ok(())
+        }
+        _ => Err(format!(
+            "unknown command `{command}`; run `cargo x --help` for usage"
+        )),
+    }
+}
+
+fn run_check(mut args: impl Iterator<Item = String>) -> Result<()> {
+    if take_help(&mut args, "check", "Check all workspace targets.")? {
+        return Ok(());
+    }
+
+    let mut command = cargo();
+    command.args(["check", "--workspace", "--all-targets"]);
+    run_command(command)
+}
+
+fn run_test(mut args: impl Iterator<Item = String>) -> Result<()> {
+    let mut no_capture = false;
+
+    for arg in args.by_ref() {
+        match arg.as_str() {
+            "--no-capture" => no_capture = true,
+            "-h" | "--help" => {
+                println!("Run all workspace tests.\n\nUsage: cargo x test [--no-capture]");
+                return Ok(());
+            }
+            _ => return Err(format!("unknown test option `{arg}`")),
+        }
+    }
+
+    let mut command = cargo();
+    command.args(["test", "--workspace", "--all-targets"]);
+    if no_capture {
+        command.args(["--", "--nocapture"]);
+    }
+    run_command(command)
+}
+
+fn run_lint(mut args: impl Iterator<Item = String>) -> Result<()> {
+    let mut fix = false;
+
+    for arg in args.by_ref() {
+        match arg.as_str() {
+            "--fix" => fix = true,
+            "-h" | "--help" => {
+                println!(
+                    "Run source, documentation, TOML, and spelling checks.\n\n\
+                     Usage: cargo x lint [--fix]"
+                );
+                return Ok(());
+            }
+            _ => return Err(format!("unknown lint option `{arg}`")),
+        }
+    }
+
+    run_format(fix)?;
+    run_clippy(fix)?;
+    run_docs()?;
+    run_taplo(fix)?;
+    run_typos()
+}
+
+fn run_licenses(mut args: impl Iterator<Item = String>) -> Result<()> {
+    if take_help(
+        &mut args,
+        "licenses",
+        "Check source headers and dependency licenses.",
+    )? {
+        return Ok(());
+    }
+
+    let mut hawkeye = workspace_command("hawkeye");
+    hawkeye.arg("check");
+    run_command(hawkeye)?;
+
+    let mut cargo = cargo();
+    cargo.args(["deny", "check", "licenses"]);
+    run_command(cargo)
+}
+
+fn run_format(fix: bool) -> Result<()> {
+    let mut command = cargo();
+    command.args(["fmt", "--all"]);
+    if !fix {
+        command.arg("--check");
+    }
+    run_command(command)
+}
+
+fn run_clippy(fix: bool) -> Result<()> {
+    let mut command = cargo();
+    command.args(["clippy", "--workspace", "--all-targets"]);
+    if fix {
+        command.args(["--fix", "--allow-dirty", "--allow-staged"]);
+    } else {
+        command.args(["--", "-D", "warnings"]);
+    }
+    run_command(command)
+}
+
+fn run_docs() -> Result<()> {
+    let mut command = cargo();
+    command.env("RUSTDOCFLAGS", "-D warnings");
+    command.args(["doc", "--workspace", "--no-deps"]);
+    run_command(command)
+}
+
+fn run_taplo(fix: bool) -> Result<()> {
+    let mut command = workspace_command("taplo");
+    command.arg("format");
+    if !fix {
+        command.arg("--check");
+    }
+    run_command(command)
+}
+
+fn run_typos() -> Result<()> {
+    run_command(workspace_command("typos"))
+}
+
+fn cargo() -> Command {
+    workspace_command("cargo")
+}
+
+fn workspace_command(program: &str) -> Command {
+    let mut command = Command::new(program);
+    command.current_dir(Path::new(env!("CARGO_WORKSPACE_DIR")));
+    command
+}
+
+fn run_command(mut command: Command) -> Result<()> {
+    println!("{command:?}");
+    let status = command.status().map_err(|error| {
+        format!(
+            "failed to run `{}`: {error}; see CONTRIBUTING.md for setup instructions",
+            command.get_program().to_string_lossy()
+        )
+    })?;
+
+    if status.success() {
+        Ok(())
+    } else {
+        Err(format!("command failed with {status}"))
+    }
+}
+
+fn take_help(
+    args: &mut impl Iterator<Item = String>,
+    command: &str,
+    description: &str,
+) -> Result<bool> {
+    match args.next() {
+        None => Ok(false),
+        Some(arg) if arg == "-h" || arg == "--help" => {
+            ensure_no_args(args)?;
+            println!("{description}\n\nUsage: cargo x {command}");
+            Ok(true)
+        }
+        Some(arg) => Err(format!("unknown {command} option `{arg}`")),
+    }
+}
+
+fn ensure_no_args(mut args: impl Iterator<Item = String>) -> Result<()> {
+    match args.next() {
+        Some(arg) => Err(format!("unexpected argument `{arg}`")),
+        None => Ok(()),
+    }
+}
+
+fn print_help() {
+    println!(
+        "Run repository tasks.\n\n\
+         Usage: cargo x <command>\n\n\
+         Commands:\n  \
+           check     Check all workspace targets\n  \
+           test      Run all workspace tests\n  \
+           lint      Run source and documentation linters\n  \
+           licenses  Check source and dependency licenses"
+    );
+}


(opendal-ofs) 02/03: docs: document repository workflows

Posted by ps...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

PsiACE pushed a commit to branch stack/xtask-tooling
in repository https://gitbox.apache.org/repos/asf/opendal-ofs.git

commit cdfbc416d9d05848a162cd25faa0710c78751786
Author: PsiACE <ps...@apache.org>
AuthorDate: Mon Aug 10 23:47:40 2026 +0800

    docs: document repository workflows
---
 AGENTS.md       | 22 ++++++++++++++++++++++
 CONTRIBUTING.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md       |  9 +++++----
 3 files changed, 78 insertions(+), 4 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..ab8340e
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,22 @@
+# Repository instructions for agents
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) before planning or modifying this
+repository.
+
+## Repository workflow
+
+Use `cargo x` as the source of truth for repository tasks. Run `cargo x --help`
+before choosing a command and `cargo x <command> --help` for command-specific
+usage.
+
+Before handing work back, run:
+
+```shell
+cargo x lint
+cargo x check
+cargo x test
+cargo x licenses
+```
+
+Keep commits focused and use semantic commit and pull request titles such as
+`feat:`, `fix:`, `docs:`, `build:`, or `ci:`.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..c81ebb6
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,51 @@
+# Contributing
+
+Thank you for contributing to Apache OpenDALâ„¢ File System.
+
+## Set up the repository
+
+Install Rust with [rustup]. The repository's `rust-toolchain.toml` selects the
+supported compiler and installs rustfmt and Clippy automatically.
+
+The lint and compliance tasks also use Taplo, typos, Hawkeye, and cargo-deny.
+Install them before running the complete check suite:
+
+```shell
+cargo install --locked taplo-cli
+cargo install --locked typos-cli
+cargo install --locked hawkeye
+cargo install --locked cargo-deny --version 0.14.22
+```
+
+## Run repository tasks
+
+The workspace provides `cargo x` as the shared entry point for local development
+and CI. Run `cargo x --help` to list its commands.
+
+- `cargo x check` checks all workspace targets.
+- `cargo x test` runs all workspace tests.
+- `cargo x lint` checks Rust formatting, Clippy, documentation, TOML formatting,
+  and spelling.
+- `cargo x licenses` checks source headers and dependency licenses.
+
+Use `cargo x lint --fix` to apply the available formatting and Clippy fixes.
+
+Before opening or updating a pull request, run:
+
+```shell
+cargo x lint
+cargo x check
+cargo x test
+cargo x licenses
+```
+
+## Prepare a change
+
+Keep runtime design, implementation, documentation, and repository tooling in
+separate commits when practical. Use semantic commit and pull request titles,
+for example `feat: add filesystem contract` or `ci: check dependency licenses`.
+
+All contributors must follow the [Apache Software Foundation Code of Conduct].
+
+[apache software foundation code of conduct]: https://www.apache.org/foundation/policies/conduct
+[rustup]: https://rustup.rs/
diff --git a/README.md b/README.md
index 3c3f94f..fbdbf75 100644
--- a/README.md
+++ b/README.md
@@ -34,12 +34,13 @@ while the new runtime is designed.
 
 ## Development
 
-Run the current project checks with:
+See [CONTRIBUTING.md] for setup instructions. Run the repository checks with:
 
 ```shell
-cargo fmt --all --check
-cargo clippy --all-targets -- -D warnings
-cargo test --all-targets
+cargo x lint
+cargo x check
+cargo x test
+cargo x licenses
 ```
 
 ## Branding


(opendal-ofs) 03/03: ci: run checks through cargo xtask

Posted by ps...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

PsiACE pushed a commit to branch stack/xtask-tooling
in repository https://gitbox.apache.org/repos/asf/opendal-ofs.git

commit 3e78f3218481e5777d5625f80909d80934ae1213
Author: PsiACE <ps...@apache.org>
AuthorDate: Mon Aug 10 23:48:12 2026 +0800

    ci: run checks through cargo xtask
---
 .github/workflows/ci.yml | 55 +++++++++++++++++++++++-------------------------
 1 file changed, 26 insertions(+), 29 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 1446f93..47d102b 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -42,44 +42,41 @@ jobs:
           rustc --version
           cargo --version
 
-      - name: Check formatting
-        run: cargo fmt --all --check
-
-      - name: Check targets
-        run: cargo check --all-targets
-
-      - name: Run Clippy
-        run: cargo clippy --all-targets -- -D warnings
+      - name: Install repository tools
+        uses: taiki-e/install-action@v2
+        with:
+          tool: taplo-cli,typos-cli
 
-      - name: Run tests
-        run: cargo test --all-targets
+      - name: Run linters
+        run: cargo x lint
 
-      - name: Build documentation
-        env:
-          RUSTDOCFLAGS: -D warnings
-        run: cargo doc --no-deps
+      - name: Check targets
+        run: cargo x check
 
-  licenses:
-    name: License headers
+  test:
+    name: Test
     runs-on: ubuntu-24.04
-    timeout-minutes: 10
+    timeout-minutes: 30
     steps:
       - uses: actions/checkout@v7
-      - name: Check license headers
-        uses: korandoru/hawkeye@v6
 
-  dependencies:
-    name: Dependencies
+      - name: Run tests
+        run: cargo x test
+
+  compliance:
+    name: Compliance
     runs-on: ubuntu-24.04
     timeout-minutes: 10
     steps:
       - uses: actions/checkout@v7
-      - name: Install cargo-deny
+
+      - name: Install repository tools
         uses: taiki-e/install-action@v2
         with:
-          tool: cargo-deny@0.14.22
-      - name: Check dependency licenses
-        run: cargo deny check licenses
+          tool: hawkeye,cargo-deny@0.14.22
+
+      - name: Check licenses
+        run: cargo x licenses
 
   required:
     name: Required
@@ -87,15 +84,15 @@ jobs:
     if: ${{ always() }}
     needs:
       - check
-      - licenses
-      - dependencies
+      - test
+      - compliance
     steps:
       - name: Guardian
         run: |
           if [[ ! ( \
                  "${{ needs.check.result }}" == "success" \
-              && "${{ needs.licenses.result }}" == "success" \
-              && "${{ needs.dependencies.result }}" == "success" \
+              && "${{ needs.test.result }}" == "success" \
+              && "${{ needs.compliance.result }}" == "success" \
               ) ]]; then
             echo "Required jobs haven't been completed successfully."
             exit 1