Add DEVELOPMENT.md guide and AGENTS.md pointer

- Created DEVELOPMENT.md as a generic technical guide for all
  contributors.
- Documented project overview, versioning, build system, and technical
  standards.
- Updated release.py to maintain version in DEVELOPMENT.md.
This commit is contained in:
François Degros
2026-04-26 16:20:53 +10:00
parent b16a337336
commit 83dcb74e3c
4 changed files with 83 additions and 2 deletions
+5
View File
@@ -0,0 +1,5 @@
{
"context": {
"fileName": ["AGENTS.md", "GEMINI.md"]
}
}
+3
View File
@@ -0,0 +1,3 @@
# AI Agent Instructions
Please follow the project standards, build instructions, and technical conventions defined in [DEVELOPMENT.md](./DEVELOPMENT.md).
+63
View File
@@ -0,0 +1,63 @@
# Development Guide for fuse-archive
This document provides project-specific context, conventions, and workflows for building and contributing to the `fuse-archive` repository.
## Project Overview
`fuse-archive` is a read-only FUSE filesystem that mounts various archive and compressed file formats (ZIP, TAR, 7Z, RAR, ISO, etc.) using the `libarchive` library. The primary implementation is contained in `fuse-archive.cc`.
## Versioning Policy
The project follows a stable/development minor versioning scheme:
- **Even minor versions** (e.g., 1.20, 1.22) are **stable** releases.
- **Odd minor versions** (e.g., 1.19, 1.21) are **development** versions.
Current state: **1.21 (Development)**.
## Build and Development
### Makefile Variables
- `DEBUG=1`: Enable debug symbols and disable optimizations.
- `ASAN=1`: Enable AddressSanitizer for memory safety checks.
### Key Makefile Targets
- `make all`: Build the `fuse-archive` binary and the man page.
- `make check-fast`: Run the fast subset of tests (recommended for most dev work).
- `make check`: Run the full test suite (including large file tests).
- `make doc`: Regenerate the `fuse-archive.1` man page from `README.md`.
- `make release`: Run the automated release workflow (see below).
- `make clean-data`: Remove large generated test archives from `test/data`.
## Documentation Pipeline
The `README.md` file serves as both the user guide and the source for the man page.
- **Generation**: `pandoc` converts `README.md` to `roff` format.
- **Formatting**: The `Makefile` uses `sed` post-processing on the `pandoc` output to ensure bulleted lists are rendered compactly (using `.PD 0`) in the man page.
- **Markdown requirement**: Bulleted lists in `README.md` **must** be preceded by a blank line for correct `pandoc` parsing.
## Release Process
The release process is fully automated via `release.py`.
- **Command**: `make release [VERSION=X.Y]`
- **Action**: Bumps version, updates dates, regenerates docs, creates a stable release commit and git tag, then bumps to the next odd development version with another commit.
- **Manual Step**: Always `git push origin main --tags` after a successful `make release`.
## Technical Standards
### Memory Safety
The project aims for full **ASAN compliance**. Always verify changes with `ASAN=1 make check-fast`.
### Resource Management (RAII)
- Use RAII guards for resource cleanup.
- **Specific Helpers**:
- `ScopedFile`: Manages file descriptors.
- `Cleanup`: A generic helper that runs a provided lambda/function in its destructor, used for one-off cleanup tasks like removing temporary mount points (e.g., `mount_point_guard`) or performing the global teardown (e.g., `global_cleanup_guard`).
- **Shutdown Performance**: The virtual node tree cleanup (`clear_and_dispose`) is wrapped in a `Cleanup` guard inside `#ifdef __SANITIZE_ADDRESS__`. It is **only** performed in ASAN builds to keep production shutdown nearly instant for archives with millions of files.
### Portability
- The project is 32-bit compatible.
- **Year 2038**: Always build with `-D_TIME_BITS=64` (handled in `Makefile`) to ensure correct timestamp handling on 32-bit systems.
## Testing
- **Main Runner**: `test/test.py`
- **Data Generation**: Large or complex test archives are generated by scripts in the `test/` directory (e.g., `make_big_zip.py`).
+12 -2
View File
@@ -53,6 +53,16 @@ def update_version(version, date=None):
with open('README.md', 'w') as f:
f.write(content)
# Update DEVELOPMENT.md
if os.path.exists('DEVELOPMENT.md'):
with open('DEVELOPMENT.md', 'r') as f:
content = f.read()
state = 'Stable' if date else 'Development'
content = re.sub(r'Current state: \*\*.*\*\*',
f'Current state: **{version} ({state})**', content)
with open('DEVELOPMENT.md', 'w') as f:
f.write(content)
# Regenerate man page
run(['make', 'doc', 'QUIET=1'])
@@ -107,13 +117,13 @@ def main():
print(f'Releasing version {version}...')
update_version(version, date)
run(['git', 'add', 'fuse-archive.cc', 'README.md', 'fuse-archive.1'])
run(['git', 'add', 'fuse-archive.cc', 'fuse-archive.1', 'DEVELOPMENT.md', 'README.md'])
run(['git', 'commit', '-m', f'Release version {version}'])
run(['git', 'tag', '-a', f'v{version}', '-m', f'Version {version}'])
print(f'Starting development version {next_version}...')
update_version(next_version)
run(['git', 'add', 'fuse-archive.cc', 'README.md', 'fuse-archive.1'])
run(['git', 'add', 'fuse-archive.cc', 'fuse-archive.1', 'DEVELOPMENT.md', 'README.md'])
run(['git', 'commit', '-m', f'Start development version {next_version}'])
print(f'\nSuccessfully released v{version} and bumped to {next_version}.')