# Contribution Guidelines
This is the standard contribution/development guidelines for the project. You may follow these to get a hold of the project quickly.
## Table of Contents
- [Getting Started](#getting-started)
- [Cloning the repository](#cloning-the-repository)
- [Preparing the environment](#preparing-the-environment)
- [Project Structure](#project-structure)
- [Production Release Workflow](#production-release-workflow)
- [Refactoring](#refactoring)
- [Build Reproduction](#build-reproduction)
- [Pull Request Guidelines](#pull-request-guidelines)
- [License](#license)
## Getting Started
The commonplace of contributing is to first clone the repository and install the dependencies.
The prerequisites are as follows:
- [Rust](https://www.rust-lang.org/tools/install) (`defaults-rs` is configured to use the 2024 edition of the language)
- A Mac (preferably with [Apple Silicon](https://support.apple.com/en-us/HT211814)) for rapid development
### Cloning the repository
Once you have ensured the prerequisites, fork the repository [from here](https://github.com/machlit/defaults-rs/fork) and clone it using the following command:
```bash
# https
$ git clone https://github.com/<your_username>/defaults-rs.git
# ssh
$ git clone git@github.com:<your_username>/defaults-rs.git
```
Replace `<your_username>` with your GitHub username.
### Preparing the environment
Working on this project will require a few Rust components beforehand:
- [clippy](https://github.com/rust-lang/rust-clippy)
- [rustfmt](https://github.com/rust-lang/rustfmt)
### Project Structure
The main source code for `defaults-rs` is located in the `src/` directory. Here is an overview of the project's structure:
```
defaults-rs/
├── src/
│ ├── cli.rs # CLI definition and argument helpers (clap-based)
│ ├── core/
│ │ ├── convert.rs # CoreFoundation <-> PrefValue conversion logic
│ │ ├── foundation.rs # CoreFoundation-based preferences backend
│ │ ├── mod.rs # Core module declarations
│ │ └── types.rs # PrefValue type definitions
│ ├── lib.rs # Library API entry point
│ ├── main.rs # CLI entry point
│ ├── preferences/
│ │ ├── convert.rs # Plist <-> PrefValue conversion logic
│ │ ├── mod.rs # Preferences API implementation
│ │ └── types.rs # Domain and FindMatch types
│ └── prettifier.rs # Apple-style pretty-printing for CLI output
├── Cargo.toml # Rust crate manifest
├── LICENSE # MIT License
└── README.md # Project documentation
```
- **src/cli.rs**: Defines the command-line interface, subcommands, and argument parsing.
- **src/core/**: Contains low-level CoreFoundation integration and type conversions.
- **src/preferences/**: Implements business logic for reading, writing, importing/exporting, and batch operations on preferences.
- **src/prettifier.rs**: Formats output in Apple-style for CLI display.
- **src/lib.rs**: Exposes the public library API.
- **src/main.rs**: Entry point for the CLI application.
## Production Release Workflow
This chain of commands can be used to fully test and build the final product.
### Refactoring
Review [this GitHub Actions workflow](./.github/workflows/refactor.yml) for refactoring reference.
> [!NOTE]
> All the workflows in this repository are run on an **Apple Silicon M1 (3-core)** runner provided by GitHub Actions. See [this page](https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources) in GitHub's documentation for more information on all the runners. If the runners used in this project get outdated and don't get a bump, you may suggest one through [GitHub Issues](https://github.com/machlit/defaults-rs/issues/new).
### Build Reproduction
You can easily create a release build for defaults-rs using the following command:
```bash
$ cargo build --release --verbose --locked
```
The major part of the release automation is currently done with [GitHub Actions]() via the [following workflow](./.github/workflows/release.yml) so, you can have a look at it to view the entire pipeline.
## Pull Request Guidelines
Before submitting a pull request, please ensure the following:
- Your code is well-documented and follows the established coding standards.
- The repository is correctly forked and your working branch is up-to-date with the latest changes from the main branch.
- All tests pass locally, and you have verified that your changes do not introduce regressions.
- If your pull request fixes an issue, mention the issue number in your PR description (e.g., Fixes #123).
- For larger changes, consider discussing your approach by opening an issue first.
Pull requests and issues must have the following pattern:
```
<type>: <title>
```
Possible types include:
- feat: New feature or enhancement
- fix: Bug fix
- docs: Documentation update
- style: Code style or formatting change
- refactor: Code refactoring without changing functionality
- test: Test-related changes
- chore: Maintenance or administrative tasks
## License
This project is licensed under the MIT License - see the [LICENSE](https://github.com/machlit/defaults-rs/blob/main/LICENSE) file for details.