From 581b051908cd134b994d61786924d093e4eba05d Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Wed, 14 Jan 2026 15:48:00 +0000 Subject: [PATCH 1/2] docs: Add AGENTS.md to CHANGELOG.md This commit updates the "Unreleased" section of the `CHANGELOG.md` to include the addition of the `AGENTS.md` file. This is a notable project change that should be tracked in the changelog. --- AGENTS.md | 16 ++++++- CHANGELOG.md | 23 ++++++++++ CONTRIBUTING.md | 89 +++++++++++++++++++++++++++++++++++++++ README.md | 109 ++++-------------------------------------------- 4 files changed, 134 insertions(+), 103 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 CONTRIBUTING.md diff --git a/AGENTS.md b/AGENTS.md index 619eb57..e42e918 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,6 +21,20 @@ The project's roadmap is outlined in the `README.md` file. However, for day-to-d - **Issue tracker > Roadmap**: The issue tracker is more tactical and pragmatic and takes precedence over the roadmap, which is more strategic and aspirational. +## Documentation + +### CONTRIBUTING.md + +The [`CONTRIBUTING.md`](./CONTRIBUTING.md) file contains instructions for setting up the development environment, running tests, and submitting pull requests. If you make changes to the development process, build steps, or quality checks, you must update this file accordingly. + +### CHANGELOG.md + +The [`CHANGELOG.md`](./CHANGELOG.md) file tracks the project's version history. For any user-visible changes, such as new features, bug fixes, or performance improvements, you must add an entry to the "Unreleased" section of this file. + ## Programmatic checks -Currently, there are no programmatic checks. This section can be updated in the future to include any checks that can be run to verify the quality of the code. +To ensure code quality, the following checks are in place. These should be run before submitting any changes. + +- **Tests**: Run the test suite with `hatch run pytest`. +- **Linting**: Check the code for style issues with `hatch run ruff check .`. +- **Type Checking**: Verify the type hints with `hatch run mypy .`. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..0858f94 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,23 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +### Added +- Table of contents display. +- Project documentation (`CONTRIBUTING.md`, `CHANGELOG.md`, `AGENTS.md`). + +### Changed +- Updated documentation for accuracy and completeness. + +## [0.1.0] - 2025-12-21 + +### Added + +- Initial release of the Imposition library. +- Core functionality for parsing EPUB files. +- Basic rendering of EPUB content in a web page. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..3b60f29 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,89 @@ +# Contributing to Imposition + +First off, thank you for considering contributing to Imposition! It's people like you that make open source such a great community. + +We welcome contributions of all kinds, from bug reports and feature requests to code and documentation. + +## How to Contribute + +### Reporting Bugs + +If you find a bug, please [open an issue](https://github.com/webmaven/imposition/issues) on our GitHub issue tracker. Please provide a clear and descriptive title, a detailed description of the problem, and steps to reproduce the bug. + +### Suggesting Enhancements + +If you have an idea for an enhancement, please [open an issue](https://github.com/webmaven/imposition/issues) to discuss it. We're always open to new ideas! + +### Pull Requests + +If you'd like to contribute code, please follow these steps: + +1. Fork the repository and create a new branch for your feature or bug fix. +2. Set up your development environment (see below). +3. Make your changes, and be sure to add or update tests as appropriate. +4. Ensure that all tests, linting, and type checks pass. +5. Open a pull request with a clear description of your changes. + +## Development Setup + +This project uses [Hatch](https://hatch.pypa.io/latest/) to manage dependencies and virtual environments. + +1. **Clone the repository:** + ```bash + git clone https://github.com/webmaven/imposition.git + cd imposition + ``` + +2. **Create the development environment:** + ```bash + hatch env create + ``` + +3. **Activate the virtual environment:** + ```bash + hatch shell + ``` + +## Building the Package + +To build the wheel for use with Pyodide: + +```bash +hatch build +``` + +This will create a `dist` directory containing the wheel file. + +## Quality Checks + +Before submitting a pull request, please ensure that your changes pass all of our quality checks. The package must be built before running the tests, as the end-to-end tests require the built wheel. + +### Running Tests + +This project uses [pytest](https://pytest.org/) for testing. To run the test suite: + +```bash +hatch run pytest +``` + +To run the tests with coverage reporting: + +```bash +hatch run pytest --cov=src/imposition +``` + +### Linting + +This project uses [Ruff](https://beta.ruff.rs/docs/) for code linting. To run the linter: + +```bash +hatch run ruff check . +``` + +### Type Checking + +This project uses [mypy](http://mypy-lang.org/) for static type checking. To run the type checker: + +```bash +hatch run mypy . +``` diff --git a/README.md b/README.md index f73d72c..7a529ae 100644 --- a/README.md +++ b/README.md @@ -38,112 +38,17 @@ if __name__ == "__main__": asyncio.run(main()) ``` -## Development Setup +## Contributing -To set up a development environment, clone the repository and use [Hatch](https://hatch.pypa.io/latest/) to manage dependencies. +Contributions are welcome! Please see the [Contributing Guidelines](CONTRIBUTING.md) for more information on how to get started. -1. **Clone the repository:** - ```bash - git clone https://github.com/webmaven/imposition.git - cd imposition - ``` +## Changelog -2. **Create the development environment:** - ```bash - hatch env create - ``` +For a detailed list of changes, please see the [Changelog](CHANGELOG.md). -3. **Activate the environment:** - ```bash - hatch shell - ``` +## License -4. **Run tests:** - ```bash - pytest - ``` - -## Building - -To build the wheel for use with Pyodide, use the following command: - -```bash -hatch build -``` - -This will create a `dist` directory with the wheel file (`imposition-0.1.0-py3-none-any.whl`). - -## Testing - -### Prerequisites - -Before running tests, ensure you have the following installed: - -1. **Python 3.13+** (or compatible version) -2. **pytest** and **pytest-playwright**: - - ```bash - pip install pytest pytest-playwright - ``` - -3. **Playwright browsers** (Chromium is required for E2E tests): - - ```bash - python -m playwright install chromium - ``` - -### Building the Package - -The E2E tests require a built wheel package. Build it using: - -```bash -pip install build -python -m build --wheel -``` - -This creates `dist/imposition-0.1.0-py3-none-any.whl`, which is loaded by the demo page during testing. - -### Running Tests - -Run all tests with: - -```bash -python -m pytest -v -``` - -For more detailed output: - -```bash -python -m pytest -vv -``` - -### Test Coverage - -The current test suite includes: - -- **E2E Test** (`tests/test_e2e.py`): Tests the complete workflow of loading an EPUB file in a browser using Pyodide, rendering it in an iframe, and verifying the content is visible. - -### Test Artifacts - -Tests generate the following artifacts: - -- **Screenshots**: `tests/screenshots/` - Contains screenshots of test runs (both passed and failed) -- **Wheel Package**: `dist/imposition-0.1.0-py3-none-any.whl` - Built package for Pyodide - -### Troubleshooting - -**Test fails with "404 - File not found" for the wheel:** - -- Make sure you've built the package first with `python -m build --wheel` - -**Test fails with "playwright: command not found":** - -- Install Playwright browsers: `python -m playwright install chromium` - -**Test times out waiting for iframe:** - -- Check that the HTTP server is running properly -- Verify that Pyodide can load from the CDN (requires internet connection) +This project is licensed under the Apache 2.0 License. See the [LICENSE](LICENSE) file for details. ## Error Handling @@ -168,7 +73,7 @@ except ImpositionError as e: For a detailed competitive analysis and the strategic reasoning behind this roadmap, please see [`COMPETITIVE_ANALYSIS.md`](./COMPETITIVE_ANALYSIS.md). -The following is a prioritized roadmap for the `Imposition` library, based on a competitive analysis of existing EPUB libraries. +**Note:** The following roadmap is a strategic overview. For the most up-to-date list of priorities, please see the [GitHub issue tracker](https://github.com/webmaven/imposition/issues). ### Phase 1: Minimum Viable Product (MVP) From 11c9d67db915dc3d624847d0fd4963625289ca22 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Wed, 14 Jan 2026 15:52:12 +0000 Subject: [PATCH 2/2] docs: Add new features to CHANGELOG.md This commit updates the "Unreleased" section of the `CHANGELOG.md` to include the addition of the custom exception hierarchy and the `LICENSE` file. These are user-visible changes that should be tracked in the changelog. --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0858f94..332cd49 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - Table of contents display. - Project documentation (`CONTRIBUTING.md`, `CHANGELOG.md`, `AGENTS.md`). +- Custom exception hierarchy for error handling. +- `LICENSE` file (Apache 2.0). ### Changed - Updated documentation for accuracy and completeness.