Skip to content

Commit 7578d87

Browse files
morr0nemorr0ne
committed
Add contributing guide
1 parent 02d92e1 commit 7578d87

File tree

2 files changed

+261
-15
lines changed

2 files changed

+261
-15
lines changed

‎CONTRIBUTING.md‎

Lines changed: 260 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,260 @@
1-
TBA
1+
# Contributing to Puppyutils
2+
3+
We welcome contributions to Puppyutils. This guide will help you understand the project and contribute effectively.
4+
5+
## Code of Conduct
6+
7+
This project follows the organization code of conduct. An up-to-date version can be found in the [here](https://github.com/puppyutils/.github/blob/main/CODE_OF_CONDUCT.md).
8+
9+
## Project Overview
10+
11+
Puppyutils is a Rust implementation of core Unix utilities focused on four key principles:
12+
13+
- **Memory Safety**: Written in Rust with zero tolerance for memory-related bugs
14+
- **Minimal Size**: Aggressive optimization for the smallest possible binary footprint
15+
- **Correctness**: Faithful implementations that match standard Unix behavior
16+
- **Clean Organization**: Maintainable codebase with consistent patterns and clear structure
17+
18+
The project uses a multi-call binary architecture where a single executable acts as different utilities based on how it's invoked (similar to BusyBox). This approach significantly reduces disk space and memory usage compared to separate binaries.
19+
20+
### Current Status
21+
22+
The project is in active development with implementations ranging from simple utilities to more complex ones with partial feature sets and ongoing development.
23+
24+
## Getting Started
25+
26+
### Prerequisites
27+
28+
- Rust nightly toolchain (automatically managed via `rust-toolchain.toml`)
29+
- Git
30+
31+
### Building
32+
33+
```bash
34+
git clone https://github.com/puppyutils/puppyutils
35+
cd puppyutils
36+
cargo build
37+
```
38+
39+
For optimized release builds: `./build-release.sh`
40+
41+
This uses nightly features and build-std for maximum size optimization.
42+
43+
## Project Structure
44+
45+
```
46+
puppyutils/
47+
├── src/
48+
│ ├── main.rs # Multi-call binary dispatcher
49+
│ ├── lib.rs # Shared library with macros and utilities
50+
│ └── bin/ # Individual utility implementations
51+
│ ├── simple.rs # Single-file utilities
52+
│ └── complex/ # Multi-file utilities
53+
│ ├── main.rs
54+
│ ├── options.rs
55+
│ └── settings.rs
56+
├── docs/ # Help text for each utility
57+
│ ├── ls.txt
58+
│ ├── cat.txt
59+
│ └── ...
60+
├── build-release.sh # Optimized build script
61+
├── rust-toolchain.toml # Pinned nightly toolchain
62+
└── CONTRIBUTING.md # This file
63+
```
64+
65+
### Key Components
66+
67+
- **`src/main.rs`**: Entry point that dispatches to appropriate utility based on binary name
68+
- **`src/lib.rs`**: Shared code including the `cli!` macro, error types, and utility functions
69+
- **`src/bin/`**: Individual utility implementations following consistent patterns
70+
- **`docs/`**: Help text files included at compile time via the `help_text!` macro
71+
72+
## Adding New Utilities
73+
74+
### 1. Implementation Structure
75+
76+
**Simple utilities** (single file):
77+
78+
```
79+
src/bin/utilname.rs
80+
```
81+
82+
**Complex utilities** (multiple files):
83+
84+
```
85+
src/bin/utilname/
86+
├── main.rs
87+
├── options.rs
88+
└── settings.rs
89+
```
90+
91+
### 2. Implementation Pattern
92+
93+
Every utility follows this template:
94+
95+
```rust
96+
use std::io::{Write, stdout};
97+
use puppyutils::{Result, cli};
98+
99+
pub fn main() -> Result {
100+
let mut stdout = stdout();
101+
102+
cli! {
103+
"utilname", stdout, #error
104+
Short('a') | Long("all") => {
105+
// Handle --all flag
106+
}
107+
Value(path) => {
108+
// Handle positional arguments
109+
}
110+
};
111+
112+
// Implementation logic here
113+
// Use rustix for system calls when possible
114+
// Write directly to stdout/stderr
115+
// Flush buffers explicitly
116+
117+
Ok(())
118+
}
119+
```
120+
121+
### 3. Registration
122+
123+
Add your utility to `src/main.rs`:
124+
125+
```rust
126+
// In the mod bin block:
127+
pub mod utilname;
128+
129+
// In the match statement:
130+
b"utilname" => bin::utilname::main(),
131+
```
132+
133+
### 4. Documentation
134+
135+
Create `docs/utilname.txt` with help text that will be shown for `--help`:
136+
137+
```
138+
Usage: utilname [OPTION]... [FILE]...
139+
Brief description of what the utility does.
140+
141+
Options:
142+
-a, --all include entries starting with .
143+
--help display this help and exit
144+
--version output version information and exit
145+
```
146+
147+
## Coding Standards
148+
149+
### Core Principles
150+
151+
- **Minimal comments**: Code should be self-documenting (exception: complex system-level code like `get_umask()`)
152+
- **Use `rustix`**: Prefer `rustix` over `std` for system calls when possible
153+
- **Direct I/O**: Write directly to stdout/stderr using `Write` trait methods
154+
- **Explicit flushing**: Always flush output buffers before returning
155+
- **Consistent errors**: Return `puppyutils::Result<T, Exit>` for error handling
156+
157+
### Performance Requirements
158+
159+
- **Minimize allocations**: Use zero-copy approaches, stack allocation, and streaming where possible
160+
- **Binary size matters**: Avoid unnecessary dependencies, use `#[inline]` judiciously
161+
- **Memory efficiency**: Consider the memory footprint of data structures
162+
163+
### Code Patterns
164+
165+
- Use the `cli!` macro for argument parsing (handles `--help` and `--version` automatically)
166+
- Use `puppyutils::Exit` enum for error types with automatic conversions
167+
- Follow existing patterns in `src/bin/` for consistency
168+
- Use `bitflags!` for option flags when appropriate
169+
- Include help text via `help_text!` macro
170+
171+
## Development Workflow
172+
173+
### Local Development
174+
175+
1. **Format code**: `cargo fmt`
176+
2. **Lint code**: `cargo clippy --all-targets --all-features`
177+
3. **Check formatting**: `cargo fmt --check`
178+
4. **Build**: `cargo build`
179+
5. **Release build**: `./build-release.sh`
180+
181+
### Testing
182+
183+
Currently, the project has minimal testing infrastructure. When implementing utilities:
184+
185+
- Test manually with various inputs and edge cases
186+
- Verify compatibility with standard Unix utilities
187+
- Check error handling and exit codes
188+
- Test `--help` and `--version` flags
189+
190+
## Submission Process
191+
192+
### 1. Preparation
193+
194+
1. Fork the repository
195+
2. Create a feature branch: `git checkout -b feature/add-utilname`
196+
3. Implement your changes following the coding standards
197+
4. Test thoroughly with manual testing
198+
199+
### 2. Code Quality
200+
201+
Before submitting:
202+
203+
```bash
204+
# Format code
205+
cargo fmt
206+
207+
# Run linting
208+
cargo clippy --all-targets --all-features
209+
210+
# Ensure it builds
211+
cargo build
212+
213+
# Test release build
214+
./build-release.sh
215+
```
216+
217+
### 3. Pull Request
218+
219+
Submit a PR with:
220+
221+
- **Clear title**: "Add utilname utility" or "Fix bug in ls option parsing"
222+
- **Detailed description**: What the change does, why it's needed, how it was tested
223+
- **Reference issues**: Link to any related issues
224+
- **Breaking changes**: Note any compatibility concerns
225+
226+
### 4. Review Process
227+
228+
PRs will be reviewed for:
229+
230+
- **Correctness**: Does it implement the utility correctly?
231+
- **Performance**: Does it follow size and speed optimization principles?
232+
- **Code style**: Does it match existing patterns and standards?
233+
- **Completeness**: Are all standard options implemented or documented as missing?
234+
235+
### 5. CI Requirements
236+
237+
All PRs must pass:
238+
239+
- **Format check**: `cargo fmt --check`
240+
- **Lint check**: `cargo clippy --all-targets --all-features`
241+
- **Build check**: Both debug and release builds must succeed
242+
- **Binary size**: Release binary size should not increase unnecessarily
243+
244+
## Getting Help
245+
246+
- **Questions**: Open an issue for questions about contributing or implementation details
247+
- **Discussions**: Use GitHub Discussions for broader architectural questions
248+
- **Issues**: Report bugs or request features via GitHub Issues
249+
250+
## Priority Areas
251+
252+
Current focus areas for contributions:
253+
254+
1. **Complete existing utilities**: Add missing options to partially implemented utilities
255+
2. **New core utilities**: Implement essential utilities following established patterns
256+
3. **Performance optimization**: Reduce allocations, improve algorithms
257+
4. **Testing infrastructure**: Set up proper testing framework
258+
5. **Documentation**: Improve help text and edge case handling
259+
260+
The goal is building a solid foundation with the most essential utilities before expanding to the full coreutils suite.

‎README.md‎

Lines changed: 1 addition & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -53,20 +53,7 @@ priorities.
5353
All utilities support standard `--help` and `--version` flags. Options after
5454
`--` will be ignored and passed as values.
5555

56-
### Project Structure
57-
58-
```
59-
src/
60-
├── bin/ # Individual utility implementations
61-
│ ├── ls/ # Complex utilities may have subdirectories
62-
│ ├── uname.rs
63-
│ ├── whoami.rs
64-
│ └── ...
65-
├── lib.rs # Shared library code and macros
66-
└── main.rs # Multi-call binary entry point
67-
```
68-
69-
### Contributing
56+
## Contributing
7057

7158
We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for
7259
guidelines on contributing to the project.

0 commit comments

Comments
 (0)