mirror of
https://github.com/google/fuse-archive.git
synced 2026-11-20 16:41:43 +00:00
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:
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"context": {
|
||||
"fileName": ["AGENTS.md", "GEMINI.md"]
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,3 @@
|
||||
# AI Agent Instructions
|
||||
|
||||
Please follow the project standards, build instructions, and technical conventions defined in [DEVELOPMENT.md](./DEVELOPMENT.md).
|
||||
@@ -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
@@ -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}.')
|
||||
|
||||
Reference in New Issue
Block a user