diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6eaa474 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,63 @@ +# Contributing +The `rbxcloud` project is open-source and welcomes PRs. If you wish to contribute to the project, please follow the guidelines listed here. + +## Purpose +The goal of the `rbxcloud` project is to provide an API and CLI tool to access Roblox's [Open Cloud](https://create.roblox.com/docs/cloud/open-cloud). As Roblox's Open Cloud matures and adds new features, the `rbxcloud` project should attempt to mirror these additions. + +## Structure +The `rbxcloud` project is split into two main chunks: +1. Rust library for accessing Roblox Open Cloud +2. CLI tool for accessing the Roblox Open Cloud + +This separation allows `rbxcloud` to be used both as a standalone CLI tool and as a library for accessing Roblox Open Cloud. + +### Rust Library +The Rust library (`src/rbx`) implements both a "low" and "high" level access into Roblox Open Cloud. + +The low-level access implementations are internal to the project, and are designed to wrap around the actual HTTP Rest endpoints that Roblox provides. These Rust function APIs are stateless and are meant to provide basic error handling around the web endpoints. + +The high-level access implementations are named "clients" and wrap around the low-level implementations. In Rust, these are structs that represent a category of endpoints (e.g. the MessagingService endpoints). These client structs are the publicly-facing APIs that end-users should be interacting with in Rust code. + +### CLI +The CLI portion (`src/cli`) of the project allows users to access the Roblox Open Cloud from the command line. + +Internally, the CLI implementation wraps around the high-level client implementations within the `rbx` library portion of the project. The CLI implementations should _not_ touch the lower-level function APIs. In other words, any CLI code should be interacting with client structs. + +CLI processing is all handled by the [`clap`](https://docs.rs/clap/latest/clap/) crate. + +## Opening PRs +Any PR should be accommodated by an associated GitHub Issue. A PR that does not have an associated GitHub Issue will be closed. + +If at all possible, do not introduce any new dependencies into the project. Similarly, any changes to the versions of current dependencies must give justification for the version changes. + +## Bug Fix PRs +When opening up a PR for a bug fix, please ensure the following: +- The associated GitHub Issue explains the bug in detail. +- The PR fixes said bug. +- The PR does not introduce new features. +- The PR explains what the new code does in order to fix the problem. +- The new code has been tested and successfully resolves the bug in question. +- Please try to not introduce any new dependencies. + +## New Feature PRs +When opening up a PR for a new feature, please ensure the following: +- The associated GitHub Issue explains the new feature in detail. +- The new feature relates directly to mirroring a Roblox Open Cloud feature that is not currently supported. +- The PR does not introduce features beyond the associated GitHub Issue. +- The new code has been tested and successfully implements the new feature in question. +- Please try to not introduce any new dependencies. + +## New Feature Expectations +When adding a new feature to support a new Roblox Open Cloud endpoint, please ensure that the code fits within the same structure as other features: + +- The "low-level" implementation should be present within the `src/rbx/vX` directory, where "X" represents the Roblox Open Cloud resource version. +- The "high-level" client implementation should be present within the `src/rbx/mod.rs` source file. This is the main API for user code, as well as the CLI. +- The CLI implementation should be present within the `src/cli` directory, and wired up within the `src/cli/mod.rs` source file. +- Documentation has been added to the `docs/cli` directory. +- The documentation `mkdocs.yml` configuration file has been updated to include any new documentation files. + +As an example, take a look at the implementation for the Universe endpoints: +- Low-level implementation: `src/rbx/v2/universe.rs`. +- High-level implementation: `src/rbx/v2/mod.rs` (search for "UniverseClient" and look at the struct and the implementation). +- CLI implementation: `src/cli/universe_cli.rs` +- CLI integration: `src/cli/mod.rs` (search for "Universe" and see its usage within the `Command` enum and the `Cli` implementation). diff --git a/Cargo.lock b/Cargo.lock index 662647a..4d450e0 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -660,7 +660,7 @@ dependencies = [ [[package]] name = "rbxcloud" -version = "0.13.0" +version = "0.14.0" dependencies = [ "anyhow", "base64 0.22.0", diff --git a/Cargo.toml b/Cargo.toml index 1e2061a..c0de43b 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "rbxcloud" -version = "0.13.0" +version = "0.14.0" description = "CLI and SDK for the Roblox Open Cloud APIs" authors = ["Stephen Leitnick"] license = "MIT" diff --git a/README.md b/README.md index 342ad8a..3007fd0 100644 --- a/README.md +++ b/README.md @@ -44,7 +44,7 @@ The goal of this project is to support all API endpoints that Roblox provides. ### Aftman Run the `aftman add` command within your project directory. This will add `rbxcloud` to the project's `aftman.toml` file (or create one if it doesn't yet exist). ```sh -$ aftman add Sleitnick/rbxcloud@0.13.0 +$ aftman add Sleitnick/rbxcloud@0.14.0 ``` ### From Release @@ -61,7 +61,7 @@ The library built for the CLI tool is available to use directly in Rust projects To use `rbxcloud` in a Rust project, simply add `rbxcloud` to the `Cargo.toml` dependency list. ```toml [dependencies] -rbxcloud = "0.13.0" +rbxcloud = "0.14.0" ``` Alternatively, use `cargo add`. diff --git a/docs/cli/cli-install.md b/docs/cli/cli-install.md index b276045..527b7a5 100644 --- a/docs/cli/cli-install.md +++ b/docs/cli/cli-install.md @@ -7,7 +7,7 @@ There are a few different ways to install the `rbxcloud` CLI. ### [Aftman](https://github.com/LPGhatguy/aftman) (Preferred) Run the `aftman add` command within your project directory. This will add `rbxcloud` to the project's `aftman.toml` file (or create one if it doesn't yet exist). ```sh -$ aftman add Sleitnick/rbxcloud@0.13.0 +$ aftman add Sleitnick/rbxcloud@0.14.0 ``` Next, run `aftman install` to install `rbxcloud`. @@ -17,7 +17,7 @@ Add `rbxcloud` under the `[tools]` section of your `foreman.toml` file. ```toml # foreman.toml [tools] -rbxcloud = { github = "Sleitnick/rbxcloud", version = "0.13.0" } +rbxcloud = { github = "Sleitnick/rbxcloud", version = "0.14.0" } ``` Next, run `foreman install` to install `rbxcloud`. diff --git a/docs/lib/lib-install.md b/docs/lib/lib-install.md index 769a4c4..effe573 100644 --- a/docs/lib/lib-install.md +++ b/docs/lib/lib-install.md @@ -5,7 +5,7 @@ To use `rbxcloud` in a Rust project, simply add `rbxcloud` to the `Cargo.toml` dependency list. ```toml [dependencies] -rbxcloud = "0.13.0" +rbxcloud = "0.14.0" ``` Alternatively, use `cargo add`.