From 55a8e38d1a0fde1d77ff63b62efc278c71eb46d4 Mon Sep 17 00:00:00 2001 From: hjnoh Date: Wed, 22 Oct 2025 19:15:31 +0900 Subject: [PATCH 1/2] DOCS: Update governance model to voidbox-led development MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Update CONTRIBUTING.md to reflect voidbox-led development model - Clarify limited capacity for external PRs - Emphasize issue reporting and small contributions - Add clear acceptance criteria for contributions - Simplify guidelines while maintaining quality standards - Update README.md contribution section - Highlight voidbox as primary maintainer - Set expectations for external contributions - Encourage bug reports and feature requests - Add GOVERNANCE.md for project governance clarity - Define company-led open source model - Outline roles and responsibilities - Document decision-making process - Establish release process and communication channels This change establishes clear expectations for community participation while maintaining the open source nature of the project. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- CONTRIBUTING.md | 229 ++++++++++++++++++------------------------------ GOVERNANCE.md | 90 +++++++++++++++++++ README.md | 12 ++- 3 files changed, 182 insertions(+), 149 deletions(-) create mode 100644 GOVERNANCE.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 58fe25e..f14591c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,211 +1,150 @@ # Contributing to py-aps -Thank you for your interest in contributing to py-aps! This document provides guidelines and instructions for contributing to the project. +Thank you for your interest in py-aps! This document provides information about how the project is developed and how you can participate. -## Getting Started +## Project Governance -1. Fork the repository -2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/pyaps.git` -3. Create a new branch: `git checkout -b your-feature-branch` -4. Make your changes -5. Commit your changes following our commit convention (see below) -6. Push to your fork: `git push origin your-feature-branch` -7. Open a Pull Request +**py-aps is maintained and developed by voidbox.** While this is an open source project (Apache-2.0 license), development is primarily led by the voidbox team to maintain consistent architecture and quality standards. -## Commit Convention +## How to Participate -We follow a structured commit message format to maintain a clear and readable project history. All commit messages should follow this pattern: +### Reporting Issues -``` -: +We welcome bug reports and feature requests! If you encounter any issues or have suggestions: -[optional body] +1. Check if the issue already exists in [GitHub Issues](https://github.com/voidbox-ai/pyaps/issues) +2. If not, create a new issue with: + - Clear title and description + - Steps to reproduce (for bugs) + - Expected vs actual behavior + - Python version, OS, and relevant environment details + - Code examples if applicable -[optional footer] -``` +### Pull Requests -### Commit Types +**Please note:** We have limited capacity to review and merge external pull requests. If you'd like to contribute code: -- **FEAT**: A new feature - ``` - FEAT: Add OAuth2 authentication flow - ``` +1. **Open an issue first** to discuss the proposed changes with the maintainers +2. Wait for approval before starting significant work +3. Small bug fixes and documentation improvements are more likely to be accepted than large feature additions -- **FIX**: A bug fix - ``` - FIX: Resolve token refresh issue in auth module - ``` +### What We Accept -- **DOCS**: Documentation changes - ``` - DOCS: Update authentication examples in README - ``` +✅ **More likely to accept:** +- Bug fixes with test cases +- Documentation improvements +- Typo corrections +- Small refactoring improvements -- **BUILD**: Changes to build system or dependencies - ``` - BUILD: Update setuptools version requirement - ``` +⚠️ **Less likely to accept:** +- New features without prior discussion +- Large architectural changes +- Breaking changes +- Dependencies additions -- **CHORE**: Routine tasks, maintenance, or tooling changes - ``` - CHORE: Update .gitignore for Python artifacts - ``` +## Development Guidelines -- **REFACTOR**: Code changes that neither fix bugs nor add features - ``` - REFACTOR: Simplify data management API client initialization - ``` +If you receive approval to work on a contribution, please follow these guidelines: -- **TEST**: Adding or updating tests - ``` - TEST: Add unit tests for authentication module - ``` +### Commit Convention -### Commit Message Guidelines +We follow a structured commit message format. All commits should follow this pattern: -1. **Subject Line** - - Use the imperative mood ("Add feature" not "Added feature") - - Keep it concise (50 characters or less) - - Capitalize the first letter after the type prefix - - Do not end with a period +``` +: + +[optional body] +``` -2. **Body** (optional) - - Provide additional context about the changes - - Explain the "why" behind the change, not just the "what" - - Wrap lines at 72 characters +#### Commit Types -3. **Footer** (optional) - - Reference related issues: `Fixes #123` or `Closes #456` - - Note breaking changes: `BREAKING CHANGE: Description of the breaking change` +- **FEAT**: A new feature +- **FIX**: A bug fix +- **DOCS**: Documentation changes +- **BUILD**: Changes to build system or dependencies +- **CHORE**: Routine tasks, maintenance, or tooling changes +- **REFACTOR**: Code changes that neither fix bugs nor add features +- **TEST**: Adding or updating tests -### Examples +#### Examples -**Simple commit:** ``` -FEAT: Add support for BIM 360 data management +FEAT: Add OAuth2 authentication flow ``` -**Commit with body:** ``` -FIX: Resolve authentication token expiration handling +FIX: Resolve token refresh issue in auth module The previous implementation did not properly handle token refresh when the access token expired during long-running operations. -This commit adds automatic token refresh logic. Fixes #42 ``` -**Breaking change:** -``` -REFACTOR: Change authentication initialization parameters - -BREAKING CHANGE: The `auth.Client()` constructor now requires -`client_id` and `client_secret` as separate parameters instead -of a single `credentials` dict. - -Migration guide: -- Before: `Client(credentials={'id': '...', 'secret': '...'})` -- After: `Client(client_id='...', client_secret='...')` -``` - -## Code Style +### Code Style - Follow [PEP 8](https://pep8.org/) style guide for Python code - Use meaningful variable and function names - Add docstrings to all public functions and classes - Keep functions focused and single-purpose -## Testing +### Testing -We use `pytest` for testing. All code contributions should include tests. +All code contributions must include tests. -### Setting Up Testing Environment +#### Setting Up Testing Environment -1. Install development dependencies: - ```bash - pip install -e ".[dev]" - ``` - -2. This will install: - - `pytest` - Testing framework - - `pytest-cov` - Code coverage plugin - - `pytest-asyncio` - Async testing support - -### Running Tests - -Run all tests: ```bash -pytest +pip install -e ".[dev]" ``` -Run tests with coverage report: -```bash -pytest --cov=pyaps --cov-report=term-missing -``` +#### Running Tests -Run specific test file: ```bash -pytest tests/test_auth.py -``` +# Run all tests +pytest -Run specific test function: -```bash -pytest tests/test_auth.py::test_oauth_flow +# Run with coverage +pytest --cov=pyaps --cov-report=term-missing ``` -### Writing Tests +#### Writing Tests - Place test files in the `tests/` directory -- Name test files with `test_` prefix (e.g., `test_auth.py`) -- Name test functions with `test_` prefix (e.g., `def test_oauth_flow()`) -- Write clear, descriptive test names that explain what is being tested -- Include docstrings for complex tests +- Name test files with `test_` prefix - Aim for high test coverage (>80%) +- All tests must pass before PR review -**Example test:** -```python -def test_authentication_with_valid_credentials(): - """Test that authentication succeeds with valid credentials.""" - client = auth.Client(client_id="valid_id", client_secret="valid_secret") - token = client.authenticate() - assert token is not None - assert token.access_token is not None -``` +### Pull Request Process -### Test Requirements +1. Fork the repository +2. Create a feature branch from `main` +3. Make your changes following the guidelines above +4. Ensure all tests pass +5. Update documentation if needed +6. Submit PR with clear description -- All new features must include tests -- All bug fixes must include regression tests -- Tests must pass on all supported Python versions (3.9, 3.10, 3.11, 3.12) -- Tests must pass on all platforms (Linux, macOS, Windows) +**Note:** PRs may take time to review. Large PRs may be closed if not previously discussed with maintainers. -### Continuous Integration +## Questions and Discussions -All pull requests automatically run tests via GitHub Actions on: -- Multiple Python versions (3.9, 3.10, 3.11, 3.12) -- Multiple operating systems (Ubuntu, Windows, macOS) +For questions about using py-aps or general discussions: +- Open a [GitHub Discussion](https://github.com/voidbox-ai/pyaps/discussions) +- Check existing issues and documentation -PRs will only be merged if all tests pass. +For security issues, please see our security policy. -## Pull Request Process +## License -1. **Update Documentation**: Update the README.md or relevant documentation for any user-facing changes -2. **Add Tests**: Include tests that cover your changes -3. **Follow Commit Convention**: Ensure your commits follow the convention outlined above -4. **Keep PRs Focused**: One PR should address one feature or fix -5. **Write Clear PR Description**: - - Summarize what the PR does - - Reference related issues - - Highlight any breaking changes - - Include testing instructions if applicable +By contributing to py-aps, you agree that your contributions will be licensed under the Apache-2.0 License. -## Questions? +## Development Roadmap -If you have questions or need help, please: -- Open an issue on GitHub -- Check existing issues and discussions +Development priorities are set by the voidbox team. You can follow our progress through: +- GitHub issues labeled with milestones +- Release notes +- Project discussions -## License +--- -By contributing to py-aps, you agree that your contributions will be licensed under the Apache-2.0 License. +Thank you for understanding our development model. We appreciate your interest in py-aps! diff --git a/GOVERNANCE.md b/GOVERNANCE.md new file mode 100644 index 0000000..5459b8b --- /dev/null +++ b/GOVERNANCE.md @@ -0,0 +1,90 @@ +# Project Governance + +## Overview + +py-aps is an open source project developed and maintained by **voidbox**. This document outlines how the project is governed and how decisions are made. + +## Governance Model + +py-aps follows a **company-led open source model**. The project is licensed under Apache-2.0, making it freely available to use, modify, and distribute, but the development direction and architecture decisions are primarily made by the voidbox team. + +## Roles and Responsibilities + +### Maintainers + +**voidbox team members** serve as the core maintainers with the following responsibilities: + +- Define the project roadmap and priorities +- Review and merge pull requests +- Make architectural decisions +- Manage releases and versioning +- Maintain documentation +- Provide technical support through GitHub Issues + +### Contributors + +Community members can contribute in the following ways: + +- **Issue Reporting**: Report bugs and request features +- **Documentation**: Improve documentation and examples +- **Code Contributions**: Submit pull requests (subject to maintainer approval) +- **Community Support**: Help other users in discussions + +## Decision Making Process + +### Development Priorities + +Development priorities and feature roadmap are set by the voidbox team based on: + +- Business requirements +- User feedback and feature requests +- Technical considerations +- Resource availability + +### Pull Request Review + +All code changes must be reviewed and approved by voidbox maintainers. The review process considers: + +- Alignment with project architecture and goals +- Code quality and test coverage +- Documentation completeness +- Maintenance burden + +**Note:** Not all pull requests may be accepted. Maintainers may close PRs that don't align with project direction or have significant maintenance concerns. + +## Communication Channels + +- **GitHub Issues**: Bug reports and feature requests +- **GitHub Discussions**: General questions and community discussions +- **GitHub Pull Requests**: Code contributions + +## Release Process + +Releases are managed by voidbox maintainers following semantic versioning (SemVer): + +- **Major versions** (x.0.0): Breaking changes +- **Minor versions** (0.x.0): New features, backward compatible +- **Patch versions** (0.0.x): Bug fixes, backward compatible + +## Code of Conduct + +We are committed to providing a welcoming and inclusive environment. All participants are expected to: + +- Be respectful and professional +- Accept constructive criticism gracefully +- Focus on what is best for the project and community +- Show empathy towards other community members + +Violations may result in temporary or permanent bans from project participation. + +## Changes to Governance + +This governance document may be updated by voidbox maintainers as the project evolves. Significant changes will be communicated through GitHub releases and announcements. + +## Questions + +For questions about project governance, please open a GitHub Discussion or contact the maintainers through GitHub Issues. + +--- + +**Maintained by voidbox** | Licensed under Apache-2.0 diff --git a/README.md b/README.md index ac158f4..2bb30d0 100644 --- a/README.md +++ b/README.md @@ -67,11 +67,15 @@ This package is currently in early development (v0.0.1). The package name has be ## Contributing -Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) before submitting a Pull Request. +py-aps is developed and maintained by **voidbox**. We welcome bug reports and feature requests through [GitHub Issues](https://github.com/voidbox-ai/pyaps/issues). -### Quick Links for Contributors -- [Contributing Guidelines](CONTRIBUTING.md) - Full contribution guide -- [Commit Convention](.github/COMMIT_CONVENTION.md) - Quick reference for commit messages +While this is an open source project, please note that we have limited capacity to review external pull requests. If you'd like to contribute code, please open an issue first to discuss your proposal with the maintainers. + +For more details, see our [Contributing Guidelines](CONTRIBUTING.md). + +### For Developers +- [Contributing Guidelines](CONTRIBUTING.md) - Participation guidelines and development standards +- [Commit Convention](.github/COMMIT_CONVENTION.md) - Commit message format reference ## License From a8035daf9aa1ef9d8a01607b3a34de6ba3d95981 Mon Sep 17 00:00:00 2001 From: hjnoh Date: Wed, 22 Oct 2025 19:17:52 +0900 Subject: [PATCH 2/2] DOCS: Simplify documentation structure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove CONTRIBUTING.md and GOVERNANCE.md files - Simplify README.md to essential information only - Remove Development section - Remove detailed contribution guidelines - Keep brief Contributing section with clear expectations - Maintain core project information This streamlines the documentation and reduces maintenance overhead while keeping essential information for users. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- CONTRIBUTING.md | 150 ------------------------------------------------ GOVERNANCE.md | 90 ----------------------------- README.md | 49 ++-------------- 3 files changed, 4 insertions(+), 285 deletions(-) delete mode 100644 CONTRIBUTING.md delete mode 100644 GOVERNANCE.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index f14591c..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,150 +0,0 @@ -# Contributing to py-aps - -Thank you for your interest in py-aps! This document provides information about how the project is developed and how you can participate. - -## Project Governance - -**py-aps is maintained and developed by voidbox.** While this is an open source project (Apache-2.0 license), development is primarily led by the voidbox team to maintain consistent architecture and quality standards. - -## How to Participate - -### Reporting Issues - -We welcome bug reports and feature requests! If you encounter any issues or have suggestions: - -1. Check if the issue already exists in [GitHub Issues](https://github.com/voidbox-ai/pyaps/issues) -2. If not, create a new issue with: - - Clear title and description - - Steps to reproduce (for bugs) - - Expected vs actual behavior - - Python version, OS, and relevant environment details - - Code examples if applicable - -### Pull Requests - -**Please note:** We have limited capacity to review and merge external pull requests. If you'd like to contribute code: - -1. **Open an issue first** to discuss the proposed changes with the maintainers -2. Wait for approval before starting significant work -3. Small bug fixes and documentation improvements are more likely to be accepted than large feature additions - -### What We Accept - -✅ **More likely to accept:** -- Bug fixes with test cases -- Documentation improvements -- Typo corrections -- Small refactoring improvements - -⚠️ **Less likely to accept:** -- New features without prior discussion -- Large architectural changes -- Breaking changes -- Dependencies additions - -## Development Guidelines - -If you receive approval to work on a contribution, please follow these guidelines: - -### Commit Convention - -We follow a structured commit message format. All commits should follow this pattern: - -``` -: - -[optional body] -``` - -#### Commit Types - -- **FEAT**: A new feature -- **FIX**: A bug fix -- **DOCS**: Documentation changes -- **BUILD**: Changes to build system or dependencies -- **CHORE**: Routine tasks, maintenance, or tooling changes -- **REFACTOR**: Code changes that neither fix bugs nor add features -- **TEST**: Adding or updating tests - -#### Examples - -``` -FEAT: Add OAuth2 authentication flow -``` - -``` -FIX: Resolve token refresh issue in auth module - -The previous implementation did not properly handle token refresh -when the access token expired during long-running operations. - -Fixes #42 -``` - -### Code Style - -- Follow [PEP 8](https://pep8.org/) style guide for Python code -- Use meaningful variable and function names -- Add docstrings to all public functions and classes -- Keep functions focused and single-purpose - -### Testing - -All code contributions must include tests. - -#### Setting Up Testing Environment - -```bash -pip install -e ".[dev]" -``` - -#### Running Tests - -```bash -# Run all tests -pytest - -# Run with coverage -pytest --cov=pyaps --cov-report=term-missing -``` - -#### Writing Tests - -- Place test files in the `tests/` directory -- Name test files with `test_` prefix -- Aim for high test coverage (>80%) -- All tests must pass before PR review - -### Pull Request Process - -1. Fork the repository -2. Create a feature branch from `main` -3. Make your changes following the guidelines above -4. Ensure all tests pass -5. Update documentation if needed -6. Submit PR with clear description - -**Note:** PRs may take time to review. Large PRs may be closed if not previously discussed with maintainers. - -## Questions and Discussions - -For questions about using py-aps or general discussions: -- Open a [GitHub Discussion](https://github.com/voidbox-ai/pyaps/discussions) -- Check existing issues and documentation - -For security issues, please see our security policy. - -## License - -By contributing to py-aps, you agree that your contributions will be licensed under the Apache-2.0 License. - -## Development Roadmap - -Development priorities are set by the voidbox team. You can follow our progress through: -- GitHub issues labeled with milestones -- Release notes -- Project discussions - ---- - -Thank you for understanding our development model. We appreciate your interest in py-aps! diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index 5459b8b..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,90 +0,0 @@ -# Project Governance - -## Overview - -py-aps is an open source project developed and maintained by **voidbox**. This document outlines how the project is governed and how decisions are made. - -## Governance Model - -py-aps follows a **company-led open source model**. The project is licensed under Apache-2.0, making it freely available to use, modify, and distribute, but the development direction and architecture decisions are primarily made by the voidbox team. - -## Roles and Responsibilities - -### Maintainers - -**voidbox team members** serve as the core maintainers with the following responsibilities: - -- Define the project roadmap and priorities -- Review and merge pull requests -- Make architectural decisions -- Manage releases and versioning -- Maintain documentation -- Provide technical support through GitHub Issues - -### Contributors - -Community members can contribute in the following ways: - -- **Issue Reporting**: Report bugs and request features -- **Documentation**: Improve documentation and examples -- **Code Contributions**: Submit pull requests (subject to maintainer approval) -- **Community Support**: Help other users in discussions - -## Decision Making Process - -### Development Priorities - -Development priorities and feature roadmap are set by the voidbox team based on: - -- Business requirements -- User feedback and feature requests -- Technical considerations -- Resource availability - -### Pull Request Review - -All code changes must be reviewed and approved by voidbox maintainers. The review process considers: - -- Alignment with project architecture and goals -- Code quality and test coverage -- Documentation completeness -- Maintenance burden - -**Note:** Not all pull requests may be accepted. Maintainers may close PRs that don't align with project direction or have significant maintenance concerns. - -## Communication Channels - -- **GitHub Issues**: Bug reports and feature requests -- **GitHub Discussions**: General questions and community discussions -- **GitHub Pull Requests**: Code contributions - -## Release Process - -Releases are managed by voidbox maintainers following semantic versioning (SemVer): - -- **Major versions** (x.0.0): Breaking changes -- **Minor versions** (0.x.0): New features, backward compatible -- **Patch versions** (0.0.x): Bug fixes, backward compatible - -## Code of Conduct - -We are committed to providing a welcoming and inclusive environment. All participants are expected to: - -- Be respectful and professional -- Accept constructive criticism gracefully -- Focus on what is best for the project and community -- Show empathy towards other community members - -Violations may result in temporary or permanent bans from project participation. - -## Changes to Governance - -This governance document may be updated by voidbox maintainers as the project evolves. Significant changes will be communicated through GitHub releases and announcements. - -## Questions - -For questions about project governance, please open a GitHub Discussion or contact the maintainers through GitHub Issues. - ---- - -**Maintained by voidbox** | Licensed under Apache-2.0 diff --git a/README.md b/README.md index 2bb30d0..536c7e3 100644 --- a/README.md +++ b/README.md @@ -26,60 +26,19 @@ from pyaps import auth # Coming soon - SDK implementation in progress ``` -## Development - -### Setting Up Development Environment - -1. Clone the repository: - ```bash - git clone https://github.com/voidbox-ai/pyaps.git - cd pyaps - ``` - -2. Install in development mode with test dependencies: - ```bash - pip install -e ".[dev]" - ``` - -### Running Tests - -Run all tests: -```bash -pytest -``` - -Run with coverage report: -```bash -pytest --cov=pyaps --cov-report=term-missing -``` - -### Continuous Integration - -All pull requests are automatically tested via GitHub Actions on: -- Python versions: 3.9, 3.10, 3.11, 3.12 -- Operating systems: Ubuntu, Windows, macOS - -Tests must pass before merging. - ## Project Status -This package is currently in early development (v0.0.1). The package name has been reserved on PyPI, and active development is underway. +This package is currently in early development (v0.0.1). The package name has been reserved on PyPI, and active development is underway by **voidbox**. ## Contributing -py-aps is developed and maintained by **voidbox**. We welcome bug reports and feature requests through [GitHub Issues](https://github.com/voidbox-ai/pyaps/issues). - -While this is an open source project, please note that we have limited capacity to review external pull requests. If you'd like to contribute code, please open an issue first to discuss your proposal with the maintainers. - -For more details, see our [Contributing Guidelines](CONTRIBUTING.md). +We welcome bug reports and feature requests through [GitHub Issues](https://github.com/voidbox-ai/pyaps/issues). -### For Developers -- [Contributing Guidelines](CONTRIBUTING.md) - Participation guidelines and development standards -- [Commit Convention](.github/COMMIT_CONVENTION.md) - Commit message format reference +This project is primarily developed by voidbox. External pull requests have limited review capacity. ## License -This project is licensed under the Apache-2.0 License - see the [LICENSE](LICENSE) file for details. +Apache-2.0 License - see the [LICENSE](LICENSE) file for details. ## Links