From ed4ac6c9fbaa5bcac7d99c96d204ce7e68af06e2 Mon Sep 17 00:00:00 2001 From: Xi Xu Date: Mon, 2 Jun 2025 00:25:49 +0800 Subject: [PATCH] Add issue templates for feature requests, performance issues, platform-specific issues, questions, and security vulnerabilities - Created detailed YAML templates for various issue types to streamline user submissions and improve issue tracking. - Added a comprehensive pull request template to guide contributors in providing necessary information. - Developed a contributing guide to outline project setup, contribution types, testing procedures, and code style guidelines. --- .github/ISSUE_TEMPLATE/bug_report.md | 38 -- .github/ISSUE_TEMPLATE/bug_report.yml | 180 +++++++++ .github/ISSUE_TEMPLATE/config.yml | 14 + .github/ISSUE_TEMPLATE/custom.md | 10 - .github/ISSUE_TEMPLATE/documentation.yml | 233 +++++++++++ .github/ISSUE_TEMPLATE/feature_request.md | 20 - .github/ISSUE_TEMPLATE/feature_request.yml | 147 +++++++ .github/ISSUE_TEMPLATE/performance_issue.yml | 219 ++++++++++ .github/ISSUE_TEMPLATE/platform_specific.yml | 239 +++++++++++ .github/ISSUE_TEMPLATE/question.yml | 206 ++++++++++ .../ISSUE_TEMPLATE/security_vulnerability.yml | 217 ++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 181 +++++++++ CONTRIBUTING.md | 374 ++++++++++++++++++ src/tzst/__init__.py | 2 +- 14 files changed, 2011 insertions(+), 69 deletions(-) delete mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml delete mode 100644 .github/ISSUE_TEMPLATE/custom.md create mode 100644 .github/ISSUE_TEMPLATE/documentation.yml delete mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/ISSUE_TEMPLATE/performance_issue.yml create mode 100644 .github/ISSUE_TEMPLATE/platform_specific.yml create mode 100644 .github/ISSUE_TEMPLATE/question.yml create mode 100644 .github/ISSUE_TEMPLATE/security_vulnerability.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CONTRIBUTING.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index dd84ea7..0000000 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -name: Bug report -about: Create a report to help us improve -title: '' -labels: '' -assignees: '' - ---- - -**Describe the bug** -A clear and concise description of what the bug is. - -**To Reproduce** -Steps to reproduce the behavior: -1. Go to '...' -2. Click on '....' -3. Scroll down to '....' -4. See error - -**Expected behavior** -A clear and concise description of what you expected to happen. - -**Screenshots** -If applicable, add screenshots to help explain your problem. - -**Desktop (please complete the following information):** - - OS: [e.g. iOS] - - Browser [e.g. chrome, safari] - - Version [e.g. 22] - -**Smartphone (please complete the following information):** - - Device: [e.g. iPhone6] - - OS: [e.g. iOS8.1] - - Browser [e.g. stock browser, safari] - - Version [e.g. 22] - -**Additional context** -Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..4a888b8 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,180 @@ +name: Bug Report +description: Report a bug or unexpected behavior in tzst +title: "[BUG] " +labels: ["bug", "needs-triage"] +assignees: [] +body: + - type: markdown + attributes: + value: | + Thank you for taking the time to report a bug! Please provide as much detail as possible to help us reproduce and fix the issue. + + - type: checkboxes + id: search + attributes: + label: Search for existing issues + description: Please search existing issues before creating a new one. + options: + - label: I have searched for existing issues and didn't find a duplicate + required: true + + - type: input + id: version + attributes: + label: tzst Version + description: What version of tzst are you using? + placeholder: "e.g., 1.0.0" + validations: + required: true + + - type: input + id: python-version + attributes: + label: Python Version + description: What version of Python are you using? + placeholder: "e.g., 3.12.0" + validations: + required: true + + - type: dropdown + id: platform + attributes: + label: Operating System + description: What operating system are you using? + options: + - Windows + - macOS + - Linux (Ubuntu) + - Linux (CentOS/RHEL) + - Linux (Arch) + - Linux (Other) + - Other + validations: + required: true + + - type: dropdown + id: usage-type + attributes: + label: Usage Type + description: How are you using tzst? + options: + - Command Line Interface (CLI) + - Python API + - Both CLI and Python API + validations: + required: true + + - type: textarea + id: description + attributes: + label: Bug Description + description: A clear and concise description of what the bug is. + placeholder: Describe what happened and what you expected to happen. + validations: + required: true + + - type: textarea + id: reproduce + attributes: + label: Steps to Reproduce + description: Detailed steps to reproduce the bug. + placeholder: | + 1. Create a file/directory structure... + 2. Run the command `tzst a archive.tzst ...` + 3. Observe the error... + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected Behavior + description: What did you expect to happen? + placeholder: Describe the expected behavior. + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual Behavior + description: What actually happened? Include any error messages or stack traces. + placeholder: | + Include full error messages, stack traces, or unexpected output here. + Use code blocks (```) for formatting. + validations: + required: true + + - type: textarea + id: archive-details + attributes: + label: Archive Details (if applicable) + description: Information about the archive or files involved. + placeholder: | + - Archive size: + - Number of files: + - File types: + - Compression level used: + - Special file types (symlinks, executables, etc.): + validations: + required: false + + - type: textarea + id: environment + attributes: + label: Environment Details + description: Additional environment information that might be relevant. + placeholder: | + - Available disk space: + - Memory (RAM): + - File system type: + - Any special permissions or restrictions: + - Antivirus software (if relevant): + validations: + required: false + + - type: dropdown + id: workaround + attributes: + label: Workaround Available + description: Have you found any workaround for this issue? + options: + - "No workaround found" + - "Partial workaround available" + - "Full workaround available" + validations: + required: false + + - type: textarea + id: workaround-details + attributes: + label: Workaround Details + description: If you found a workaround, please describe it here. + placeholder: Describe any workaround you've found. + validations: + required: false + + - type: checkboxes + id: additional-info + attributes: + label: Additional Information + description: Please check any that apply to your situation. + options: + - label: This is a regression (worked in a previous version) + - label: This affects large files (>100MB) + - label: This affects archives with many files (>1000) + - label: This involves Unicode/international characters + - label: This involves symbolic links or special files + - label: This affects atomic file operations + - label: This affects streaming mode + - label: This involves compression level edge cases + - label: This is platform-specific behavior + + - type: textarea + id: additional-context + attributes: + label: Additional Context + description: Any other context, screenshots, or information that might help. + placeholder: Add any other context about the problem here. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..468cb38 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,14 @@ +blank_issues_enabled: false +contact_links: + - name: πŸ“– Documentation + url: https://github.com/xixu-me/tzst#readme + about: Check the README for usage instructions and examples + - name: πŸ”’ Security Vulnerabilities (Private) + url: mailto:security@xi-xu.me + about: For critical security vulnerabilities, please report privately via email + - name: πŸ’¬ Discussions + url: https://github.com/xixu-me/tzst/discussions + about: Ask questions and discuss ideas with the community + - name: πŸ“Š PyPI Package + url: https://pypi.org/project/tzst/ + about: Download and install tzst from PyPI diff --git a/.github/ISSUE_TEMPLATE/custom.md b/.github/ISSUE_TEMPLATE/custom.md deleted file mode 100644 index 48d5f81..0000000 --- a/.github/ISSUE_TEMPLATE/custom.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -name: Custom issue template -about: Describe this issue template's purpose here. -title: '' -labels: '' -assignees: '' - ---- - - diff --git a/.github/ISSUE_TEMPLATE/documentation.yml b/.github/ISSUE_TEMPLATE/documentation.yml new file mode 100644 index 0000000..e5cdf78 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/documentation.yml @@ -0,0 +1,233 @@ +name: Documentation Issue +description: Report issues with documentation, examples, or request documentation improvements +title: "[DOCS] " +labels: ["documentation", "needs-triage"] +assignees: [] +body: + - type: markdown + attributes: + value: | + Thank you for helping improve tzst documentation! Clear documentation is essential for user experience. + + - type: checkboxes + id: search + attributes: + label: Search for existing issues + description: Please search existing issues before creating a new one. + options: + - label: I have searched for existing documentation issues and didn't find a duplicate + required: true + + - type: dropdown + id: doc-type + attributes: + label: Documentation Type + description: What type of documentation issue is this? + options: + - README.md + - CONTRIBUTING.md + - API documentation (docstrings) + - CLI help text + - Code examples + - Installation instructions + - Error messages + - Security documentation + - Performance guidelines + - Platform-specific notes + - Other + validations: + required: true + + - type: dropdown + id: issue-category + attributes: + label: Issue Category + description: What type of documentation issue are you reporting? + options: + - Missing documentation + - Incorrect/outdated information + - Unclear or confusing explanation + - Missing examples + - Broken links or references + - Formatting issues + - Typos or grammar errors + - Translation issues + - Accessibility improvements + - New documentation request + validations: + required: true + + - type: textarea + id: description + attributes: + label: Issue Description + description: Describe the documentation issue in detail. + placeholder: | + Clearly describe the documentation problem: + - What information is missing, incorrect, or unclear? + - Where did you encounter this issue? + - What were you trying to accomplish? + validations: + required: true + + - type: textarea + id: location + attributes: + label: Documentation Location + description: Where is this documentation located? + placeholder: | + Specify the location: + - File name: README.md, CONTRIBUTING.md, etc. + - Section: "Installation", "API Reference", etc. + - Line numbers (if applicable): + - URL (if online documentation): + validations: + required: true + + - type: textarea + id: current-content + attributes: + label: Current Content + description: What does the current documentation say? (copy the relevant text) + placeholder: | + Copy the current text that is problematic: + ``` + [Paste current documentation text here] + ``` + validations: + required: false + + - type: textarea + id: expected-content + attributes: + label: Suggested Improvement + description: What should the documentation say instead? + placeholder: | + Provide your suggested improvement: + - Corrected information + - Clearer explanation + - Additional examples + - Better formatting + validations: + required: true + + - type: textarea + id: examples-needed + attributes: + label: Examples Needed + description: What examples would help illustrate this documentation? + placeholder: | + Suggest specific examples: + - Code examples showing usage + - Command-line examples + - Common use cases + - Error handling examples + validations: + required: false + + - type: dropdown + id: user-level + attributes: + label: Target User Level + description: What level of user would benefit from this documentation improvement? + options: + - Beginner (first-time users) + - Intermediate (some experience) + - Advanced (power users) + - Developer (contributing to tzst) + - All users + validations: + required: false + + - type: checkboxes + id: documentation-areas + attributes: + label: Related Documentation Areas + description: Which areas of documentation are related to this issue? + options: + - label: Installation and setup + - label: Basic usage and getting started + - label: CLI commands and options + - label: Python API reference + - label: Performance and optimization + - label: Security considerations + - label: Platform-specific information + - label: Troubleshooting and error handling + - label: Advanced usage patterns + - label: Integration with other tools + - label: Contributing guidelines + - label: Development setup + + - type: dropdown + id: discovery-context + attributes: + label: How did you discover this issue? + description: What were you doing when you found this documentation problem? + options: + - Reading documentation to learn tzst + - Following installation instructions + - Looking for specific API information + - Trying to solve a problem + - Reviewing code examples + - Contributing to the project + - Teaching/helping others + - Other + validations: + required: false + + - type: textarea + id: user-journey + attributes: + label: User Journey Context + description: Describe what you were trying to accomplish when you encountered this issue. + placeholder: | + Help us understand the context: + - What task were you trying to complete? + - What information were you looking for? + - What confusion or frustration did you experience? + - How did this impact your ability to use tzst? + validations: + required: false + + - type: checkboxes + id: improvement-type + attributes: + label: Improvement Type + description: What type of improvement would help most? + options: + - label: More detailed explanations + - label: Step-by-step tutorials + - label: More code examples + - label: Better organization/structure + - label: Visual aids (diagrams, screenshots) + - label: Cross-references to related topics + - label: Troubleshooting guides + - label: FAQ section + - label: Video or interactive content + - label: Beginner-friendly explanations + - label: Advanced technical details + + - type: textarea + id: additional-context + attributes: + label: Additional Context + description: Any other context that would help improve the documentation. + placeholder: | + Additional information: + - Your experience level with similar tools + - Documentation from other projects that you found helpful + - Specific use cases that need better coverage + - Any other relevant details + validations: + required: false + + - type: checkboxes + id: contribution-interest + attributes: + label: Contribution Interest + description: Would you be interested in helping improve this documentation? + options: + - label: I would be interested in writing/improving this documentation + - label: I would be interested in reviewing documentation changes + - label: I can provide feedback on documentation drafts + - label: I can help with testing documentation examples diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md deleted file mode 100644 index bbcbbe7..0000000 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -name: Feature request -about: Suggest an idea for this project -title: '' -labels: '' -assignees: '' - ---- - -**Is your feature request related to a problem? Please describe.** -A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] - -**Describe the solution you'd like** -A clear and concise description of what you want to happen. - -**Describe alternatives you've considered** -A clear and concise description of any alternative solutions or features you've considered. - -**Additional context** -Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..9639a10 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,147 @@ +name: Feature Request +description: Suggest a new feature or enhancement for tzst +title: "[FEATURE] " +labels: ["enhancement", "needs-triage"] +assignees: [] +body: + - type: markdown + attributes: + value: | + Thank you for suggesting a new feature! Please provide as much detail as possible about your request. + + - type: checkboxes + id: search + attributes: + label: Search for existing requests + description: Please search existing issues and discussions before creating a new feature request. + options: + - label: I have searched for existing feature requests and didn't find a duplicate + required: true + + - type: dropdown + id: feature-type + attributes: + label: Feature Type + description: What type of feature are you requesting? + options: + - New CLI command or option + - New Python API functionality + - Performance improvement + - New compression options + - Enhanced error handling + - Security enhancement + - Cross-platform compatibility + - Integration with other tools + - Documentation improvement + - Other + validations: + required: true + + - type: textarea + id: problem + attributes: + label: Problem Description + description: What problem would this feature solve? What use case would it enable? + placeholder: | + Describe the problem or limitation you're experiencing. + What use case would this feature enable? + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Proposed Solution + description: Describe the solution you'd like to see implemented. + placeholder: | + Describe your proposed solution in detail. + How would users interact with this feature? + validations: + required: true + + - type: textarea + id: examples + attributes: + label: Usage Examples + description: Provide examples of how this feature would be used. + placeholder: | + # CLI example: + tzst new-command archive.tzst --new-option + + # Python API example: + from tzst import TzstArchive + with TzstArchive("archive.tzst") as archive: + archive.new_method() + validations: + required: false + + - type: textarea + id: alternatives + attributes: + label: Alternatives Considered + description: What alternatives have you considered? Why isn't the current functionality sufficient? + placeholder: | + Describe any alternative solutions you've considered. + Why don't existing features meet your needs? + validations: + required: false + + - type: dropdown + id: priority + attributes: + label: Priority Level + description: How important is this feature to you? + options: + - Critical (blocks important workflows) + - High (would significantly improve workflow) + - Medium (nice to have) + - Low (minor convenience) + validations: + required: false + + - type: checkboxes + id: compatibility + attributes: + label: Compatibility Considerations + description: Please check any that apply to your feature request. + options: + - label: This feature should maintain backward compatibility + - label: This feature may require breaking changes + - label: This feature should work on all supported platforms + - label: This feature is platform-specific + - label: This feature affects file format compatibility + - label: This feature affects performance significantly + - label: This feature requires new dependencies + + - type: textarea + id: implementation + attributes: + label: Implementation Ideas + description: Do you have any ideas about how this could be implemented? + placeholder: | + If you have technical knowledge about how this could be implemented, + please share your ideas here. This is optional but helpful. + validations: + required: false + + - type: checkboxes + id: contribution + attributes: + label: Contribution Interest + description: Would you be interested in contributing to this feature? + options: + - label: I would be interested in implementing this feature + - label: I would be interested in testing this feature + - label: I would be interested in writing documentation for this feature + - label: I can provide ongoing feedback during development + + - type: textarea + id: additional-context + attributes: + label: Additional Context + description: Any other context, links, or information that would help understand this request. + placeholder: | + Add any other context about the feature request here. + Links to similar features in other tools, academic papers, etc. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/performance_issue.yml b/.github/ISSUE_TEMPLATE/performance_issue.yml new file mode 100644 index 0000000..ed336fb --- /dev/null +++ b/.github/ISSUE_TEMPLATE/performance_issue.yml @@ -0,0 +1,219 @@ +name: Performance Issue +description: Report performance problems, memory usage, or speed issues +title: "[PERFORMANCE] " +labels: ["performance", "needs-triage"] +assignees: [] +body: + - type: markdown + attributes: + value: | + Thank you for reporting a performance issue! Performance problems can be tricky to diagnose, so please provide as much detail as possible. + + - type: checkboxes + id: search + attributes: + label: Search for existing issues + description: Please search existing issues before creating a new one. + options: + - label: I have searched for existing performance issues and didn't find a duplicate + required: true + + - type: input + id: version + attributes: + label: tzst Version + description: What version of tzst are you using? + placeholder: "e.g., 1.0.0" + validations: + required: true + + - type: input + id: python-version + attributes: + label: Python Version + description: What version of Python are you using? + placeholder: "e.g., 3.12.0" + validations: + required: true + + - type: dropdown + id: platform + attributes: + label: Operating System + description: What operating system are you using? + options: + - Windows + - macOS + - Linux (Ubuntu) + - Linux (CentOS/RHEL) + - Linux (Arch) + - Linux (Other) + - Other + validations: + required: true + + - type: dropdown + id: performance-type + attributes: + label: Performance Issue Type + description: What type of performance problem are you experiencing? + options: + - Slow compression speed + - Slow decompression speed + - High memory usage + - High CPU usage + - Slow file I/O + - Poor scaling with large files + - Poor scaling with many files + - Streaming mode performance + - CLI responsiveness + - Other + validations: + required: true + + - type: textarea + id: description + attributes: + label: Performance Issue Description + description: Describe the performance problem you're experiencing. + placeholder: | + Describe what performance issue you're seeing. + Be specific about what operations are slow or using too much memory. + validations: + required: true + + - type: textarea + id: benchmark-data + attributes: + label: Benchmark Data + description: Provide timing, memory usage, or other measurable data. + placeholder: | + Operation: Creating 1GB archive + Time taken: 45 seconds + Memory usage: 2GB RAM + CPU usage: 100% for entire duration + + Expected: ~15 seconds, <500MB RAM + validations: + required: true + + - type: textarea + id: data-characteristics + attributes: + label: Data Characteristics + description: Describe the files/data you're working with. + placeholder: | + - Total size: + - Number of files: + - File types: + - Average file size: + - Directory structure depth: + - Compression level used: + - Archive format (.tzst or .tar.zst): + validations: + required: true + + - type: textarea + id: system-specs + attributes: + label: System Specifications + description: Provide details about your system hardware. + placeholder: | + - CPU: + - RAM: + - Storage type (SSD/HDD): + - Available disk space: + - Network storage (if applicable): + validations: + required: true + + - type: dropdown + id: usage-pattern + attributes: + label: Usage Pattern + description: How are you using tzst? + options: + - Command Line Interface (CLI) + - Python API with small archives + - Python API with large archives + - Python API with many small files + - Streaming mode + - Batch processing multiple archives + - Interactive usage + validations: + required: true + + - type: textarea + id: reproduce + attributes: + label: Steps to Reproduce + description: Detailed steps to reproduce the performance issue. + placeholder: | + 1. Create test data of size X... + 2. Run command `tzst a archive.tzst ...` + 3. Monitor performance with [tool]... + 4. Observe slow performance... + validations: + required: true + + - type: textarea + id: comparison + attributes: + label: Performance Comparison + description: How does tzst performance compare to other tools or previous versions? + placeholder: | + Comparison with other tools (tar, gzip, etc.): + - Tool A: X seconds, Y MB memory + - Tool B: X seconds, Y MB memory + - tzst: X seconds, Y MB memory + + Comparison with previous tzst versions (if applicable): + - Version X.X.X: timing/memory + - Current version: timing/memory + validations: + required: false + + - type: checkboxes + id: performance-factors + attributes: + label: Performance Factors + description: Please check any that apply to your situation. + options: + - label: Issue occurs with atomic file operations enabled + - label: Issue occurs with streaming mode enabled + - label: Issue occurs with high compression levels (15+) + - label: Issue occurs with low compression levels (1-5) + - label: Issue occurs with Unicode filenames + - label: Issue occurs with symbolic links + - label: Issue occurs with many small files + - label: Issue occurs with few large files + - label: Issue occurs on network storage + - label: Issue occurs during extraction + - label: Issue occurs during compression + - label: Issue is reproducible consistently + + - type: textarea + id: profiling-data + attributes: + label: Profiling Data + description: If you've done any profiling, please include the results. + placeholder: | + Include any profiling data you've collected: + - Python profiler output + - Memory profiler results + - System monitoring data + - etc. + validations: + required: false + + - type: textarea + id: additional-context + attributes: + label: Additional Context + description: Any other context that might help diagnose the performance issue. + placeholder: | + - Are you running other resource-intensive programs? + - Any specific system configurations? + - Any other relevant details? + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/platform_specific.yml b/.github/ISSUE_TEMPLATE/platform_specific.yml new file mode 100644 index 0000000..8fd7e9f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/platform_specific.yml @@ -0,0 +1,239 @@ +name: Platform-Specific Issue +description: Report issues specific to Windows, macOS, Linux, or other platforms +title: "[PLATFORM] " +labels: ["platform-specific", "needs-triage"] +assignees: [] +body: + - type: markdown + attributes: + value: | + Thank you for reporting a platform-specific issue! These issues help us ensure tzst works correctly across all supported platforms. + + - type: checkboxes + id: search + attributes: + label: Search for existing issues + description: Please search existing issues before creating a new one. + options: + - label: I have searched for existing platform-specific issues and didn't find a duplicate + required: true + + - type: input + id: version + attributes: + label: tzst Version + description: What version of tzst are you using? + placeholder: "e.g., 1.0.0" + validations: + required: true + + - type: input + id: python-version + attributes: + label: Python Version + description: What version of Python are you using? + placeholder: "e.g., 3.12.0" + validations: + required: true + + - type: dropdown + id: platform + attributes: + label: Primary Platform (where issue occurs) + description: What operating system are you experiencing the issue on? + options: + - Windows 11 + - Windows 10 + - Windows (other version) + - macOS (latest) + - macOS (older version) + - Ubuntu (latest LTS) + - Ubuntu (other version) + - CentOS/RHEL + - Arch Linux + - Alpine Linux + - Debian + - Other Linux distribution + - FreeBSD + - Other Unix-like OS + validations: + required: true + + - type: input + id: platform-details + attributes: + label: Platform Details + description: Specific version, architecture, or other platform details. + placeholder: "e.g., Windows 10 Pro 22H2, x64 / Ubuntu 22.04.3 LTS, arm64 / macOS 13.5, x86_64" + validations: + required: true + + - type: dropdown + id: cross-platform-test + attributes: + label: Cross-Platform Testing + description: Have you tested this on other platforms? + options: + - "No, only tested on the affected platform" + - "Yes, works correctly on other platforms" + - "Yes, same issue occurs on other platforms" + - "Partially tested on other platforms" + validations: + required: true + + - type: textarea + id: other-platforms + attributes: + label: Other Platform Results + description: If you tested on other platforms, what were the results? + placeholder: | + Platform 1: Working correctly / Same issue / Different issue / Not tested + Platform 2: Working correctly / Same issue / Different issue / Not tested + Platform 3: Working correctly / Same issue / Different issue / Not tested + validations: + required: false + + - type: dropdown + id: issue-category + attributes: + label: Issue Category + description: What type of platform-specific issue is this? + options: + - File path handling (Windows path limits, Unix paths) + - File permissions and attributes + - Symbolic links and special files + - Character encoding and Unicode + - File system limitations + - Archive compatibility across platforms + - CLI behavior differences + - Installation or packaging issues + - Performance differences + - Security or permissions model + - Other + validations: + required: true + + - type: textarea + id: description + attributes: + label: Issue Description + description: Describe the platform-specific issue you're experiencing. + placeholder: | + Describe the issue in detail. + Be specific about what behavior you're seeing that differs from expected or from other platforms. + validations: + required: true + + - type: textarea + id: reproduce + attributes: + label: Steps to Reproduce + description: Steps to reproduce the issue on the affected platform. + placeholder: | + 1. Create files with [specific characteristics]... + 2. Run `tzst a archive.tzst ...` + 3. Observe platform-specific behavior... + validations: + required: true + + - type: textarea + id: expected-behavior + attributes: + label: Expected Behavior + description: What behavior did you expect? How does it work on other platforms? + placeholder: | + Expected behavior (or behavior on other platforms): + - Should create archive successfully + - Should preserve file attributes + - etc. + validations: + required: true + + - type: textarea + id: actual-behavior + attributes: + label: Actual Behavior + description: What actually happens on this platform? + placeholder: | + Actual behavior on [platform]: + - Error message: + - Unexpected results: + - Different file handling: + validations: + required: true + + - type: checkboxes + id: platform-features + attributes: + label: Platform-Specific Features Involved + description: Check any platform-specific features that are involved in this issue. + options: + - label: Windows long paths (>260 characters) + - label: Windows reserved filenames (CON, PRN, AUX, etc.) + - label: Windows file attributes (hidden, system, etc.) + - label: Windows case-insensitive filesystem + - label: Unix/Linux file permissions (chmod) + - label: Unix/Linux symbolic links + - label: Unix/Linux hard links + - label: Unix/Linux special files (devices, pipes, etc.) + - label: macOS resource forks or extended attributes + - label: macOS case-insensitive but case-preserving filesystem + - label: Unicode normalization differences + - label: Path separator differences (/ vs \) + - label: Network filesystem behaviors + - label: Container or virtualized environment + + - type: textarea + id: file-examples + attributes: + label: Problematic File Examples + description: Provide examples of files or paths that cause issues. + placeholder: | + Examples of files that cause problems: + - "CON.txt" (Windows reserved name) + - "file with very long path/..." (path length issues) + - "Ρ„Π°ΠΉΠ».txt" (Unicode characters) + - Symbolic link: link -> target + validations: + required: false + + - type: textarea + id: environment-details + attributes: + label: Environment Details + description: Additional environment information specific to your platform. + placeholder: | + - Filesystem type: NTFS/ext4/APFS/etc. + - Case sensitivity: case-sensitive/case-insensitive + - Python installation method: system/conda/pyenv/etc. + - Admin/root privileges: yes/no + - Antivirus software (if Windows): + - Container environment: Docker/WSL/etc. + validations: + required: false + + - type: textarea + id: workaround + attributes: + label: Workaround + description: Have you found any platform-specific workarounds? + placeholder: | + Any workarounds you've discovered for this platform: + - Using different file names + - Different command options + - Platform-specific configuration + validations: + required: false + + - type: textarea + id: additional-context + attributes: + label: Additional Context + description: Any other platform-specific context that might be relevant. + placeholder: | + - Related to company/enterprise policies? + - Specific hardware configurations? + - Network or security restrictions? + - Other relevant platform details? + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml new file mode 100644 index 0000000..6253c87 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.yml @@ -0,0 +1,206 @@ +name: Question or Support +description: Ask a question about using tzst or get help with a specific use case +title: "[QUESTION] " +labels: ["question", "support"] +assignees: [] +body: + - type: markdown + attributes: + value: | + Welcome! We're happy to help you with tzst. Please provide as much detail as possible so we can give you the best assistance. + + **Note:** For general questions, you might also consider: + - Checking the [README.md](../README.md) for common usage patterns + - Looking at existing issues for similar questions + - Reviewing the Python API documentation in the code + + - type: checkboxes + id: search + attributes: + label: Search for existing answers + description: Please search existing issues and documentation before asking. + options: + - label: I have searched existing issues and documentation for an answer + required: true + + - type: dropdown + id: question-type + attributes: + label: Question Type + description: What type of question do you have? + options: + - How to use a specific feature + - Best practices recommendation + - Performance optimization help + - Platform-specific usage + - Integration with other tools + - Troubleshooting help + - Feature availability/roadmap + - Contributing guidance + - Other + validations: + required: true + + - type: textarea + id: question + attributes: + label: Your Question + description: What would you like to know about tzst? + placeholder: | + Ask your question clearly and specifically: + - What are you trying to accomplish? + - What specific help do you need? + - What have you already tried? + validations: + required: true + + - type: textarea + id: context + attributes: + label: Context and Use Case + description: Provide context about your situation and what you're trying to accomplish. + placeholder: | + Help us understand your situation: + - What are you building or working on? + - What constraints or requirements do you have? + - Why are you using tzst for this task? + - What's your experience level with similar tools? + validations: + required: true + + - type: textarea + id: attempted-solutions + attributes: + label: What You've Tried + description: What have you already attempted? Include code, commands, or approaches you've tried. + placeholder: | + Describe what you've already tried: + ```bash + # Command you tried + tzst a archive.tzst files/ + ``` + + ```python + # Python code you tried + from tzst import create_archive + create_archive("test.tzst", ["files/"]) + ``` + + - Approach 1: [what happened] + - Approach 2: [what happened] + validations: + required: false + + - type: input + id: tzst-version + attributes: + label: tzst Version + description: What version of tzst are you using? + placeholder: "e.g., 1.0.0" + validations: + required: false + + - type: dropdown + id: platform + attributes: + label: Platform + description: What platform are you using? + options: + - Windows + - macOS + - Linux + - Not platform-specific + - Multiple platforms + validations: + required: false + + - type: dropdown + id: usage-context + attributes: + label: Usage Context + description: How are you planning to use tzst? + options: + - Command line tool for personal use + - Command line tool in scripts/automation + - Python library in application + - Python library for data processing + - Integration with existing workflow + - Learning/educational purposes + - Contributing to tzst development + - Other + validations: + required: false + + - type: textarea + id: data-characteristics + attributes: + label: Data Characteristics (if relevant) + description: If your question involves specific types of data, describe it. + placeholder: | + If relevant to your question: + - Types of files you're working with: + - Approximate data size: + - Number of files: + - Special requirements (performance, security, etc.): + validations: + required: false + + - type: textarea + id: expected-outcome + attributes: + label: Desired Outcome + description: What would be the ideal solution or outcome for your question? + placeholder: | + Describe what you're hoping to achieve: + - Specific functionality you want + - Performance characteristics needed + - Integration requirements + - etc. + validations: + required: false + + - type: checkboxes + id: help-areas + attributes: + label: Areas Where You Need Help + description: Check the areas where you need assistance. + options: + - label: Understanding basic tzst concepts + - label: Choosing the right commands/API methods + - label: Optimizing performance + - label: Handling large files or archives + - label: Platform-specific considerations + - label: Error handling and troubleshooting + - label: Security considerations + - label: Integration with other tools/workflows + - label: Python API usage + - label: CLI usage and scripting + - label: Compression settings and trade-offs + - label: File format compatibility + + - type: dropdown + id: urgency + attributes: + label: Urgency Level + description: How urgent is this question for you? + options: + - Not urgent (general learning) + - Somewhat urgent (current project) + - Urgent (blocking my work) + - Very urgent (production issue) + validations: + required: false + + - type: textarea + id: additional-info + attributes: + label: Additional Information + description: Any other information that might help us answer your question. + placeholder: | + Anything else that might be relevant: + - Links to similar questions or resources you've found + - Specific error messages (if applicable) + - Related tools or technologies you're using + - Any constraints or limitations you're working with + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/security_vulnerability.yml b/.github/ISSUE_TEMPLATE/security_vulnerability.yml new file mode 100644 index 0000000..87e94b2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/security_vulnerability.yml @@ -0,0 +1,217 @@ +name: Security Vulnerability +description: Report a security vulnerability in tzst (please follow responsible disclosure) +title: "[SECURITY] " +labels: ["security", "needs-triage"] +assignees: [] +body: + - type: markdown + attributes: + value: | + # Security Vulnerability Report + + **⚠️ IMPORTANT: For serious security vulnerabilities, please consider using private reporting instead of a public issue.** + + If this is a critical security vulnerability that could be exploited, please: + 1. Email the maintainers privately first + 2. Allow time for a security patch before public disclosure + 3. Follow responsible disclosure practices + + For less critical security issues or general security improvements, this public issue form is appropriate. + + - type: checkboxes + id: disclosure + attributes: + label: Responsible Disclosure + description: Please confirm your approach to reporting this security issue. + options: + - label: I understand the importance of responsible disclosure for security vulnerabilities + required: true + - label: This is not a critical vulnerability that requires private reporting + required: true + - label: I have considered the potential impact of public disclosure + required: true + + - type: dropdown + id: severity + attributes: + label: Severity Level + description: How severe do you consider this security issue? + options: + - Critical (immediate action required) + - High (significant security risk) + - Medium (moderate security concern) + - Low (minor security improvement) + - Informational (security-related best practice) + validations: + required: true + + - type: dropdown + id: vulnerability-type + attributes: + label: Vulnerability Type + description: What type of security issue is this? + options: + - Path traversal / Directory traversal + - Archive bomb / Zip bomb + - Arbitrary file overwrite + - Symlink attack + - Information disclosure + - Denial of Service (DoS) + - Memory corruption + - Injection vulnerability + - Privilege escalation + - Cryptographic weakness + - Input validation bypass + - Other + validations: + required: true + + - type: textarea + id: description + attributes: + label: Vulnerability Description + description: Describe the security vulnerability in detail. + placeholder: | + Provide a clear description of the security issue: + - What component is affected? + - What is the vulnerability? + - What are the potential consequences? + validations: + required: true + + - type: textarea + id: attack-scenario + attributes: + label: Attack Scenario + description: Describe how this vulnerability could be exploited. + placeholder: | + Describe a realistic attack scenario: + 1. Attacker creates malicious archive with... + 2. Victim extracts archive using tzst... + 3. Result: files written outside extraction directory / code execution / etc. + validations: + required: true + + - type: textarea + id: impact + attributes: + label: Impact Assessment + description: What is the potential impact of this vulnerability? + placeholder: | + Describe the potential impact: + - Confidentiality: Can sensitive data be exposed? + - Integrity: Can files be modified unexpectedly? + - Availability: Can the system be made unavailable? + - Scope: Who would be affected? + validations: + required: true + + - type: textarea + id: affected-versions + attributes: + label: Affected Versions + description: Which versions of tzst are affected by this vulnerability? + placeholder: | + - tzst version tested: + - Likely affected versions: + - Known safe versions (if any): + validations: + required: true + + - type: textarea + id: reproduce + attributes: + label: Proof of Concept + description: Provide steps to reproduce or demonstrate the vulnerability. + placeholder: | + **WARNING: Please ensure your PoC is safe and doesn't cause actual harm** + + Steps to reproduce: + 1. Create test archive with specific structure... + 2. Run tzst command... + 3. Observe security issue... + + Or provide code that demonstrates the issue safely. + validations: + required: true + + - type: textarea + id: mitigation + attributes: + label: Suggested Mitigation + description: Do you have suggestions for how to fix this vulnerability? + placeholder: | + Suggested fixes or mitigations: + - Input validation improvements + - Security filter enhancements + - API changes needed + - Configuration options + validations: + required: false + + - type: checkboxes + id: security-features + attributes: + label: Related Security Features + description: Which tzst security features are involved? + options: + - label: Extraction filters (data, tar, etc.) + - label: Path validation + - label: Symlink handling + - label: Archive format validation + - label: Memory limits + - label: File size limits + - label: Atomic operations + - label: Temporary file handling + - label: Error handling and cleanup + + - type: textarea + id: references + attributes: + label: References + description: Any relevant CVEs, security advisories, or research papers. + placeholder: | + Related security research: + - CVE numbers: + - Security advisories: + - Research papers: + - Similar vulnerabilities in other tools: + validations: + required: false + + - type: textarea + id: environment + attributes: + label: Environment Details + description: Platform and environment details relevant to this vulnerability. + placeholder: | + - Operating System: + - Python version: + - tzst version: + - Specific environment factors: + validations: + required: false + + - type: checkboxes + id: disclosure-timeline + attributes: + label: Disclosure Timeline + description: What is your intended disclosure timeline? + options: + - label: I plan to disclose this publicly immediately + - label: I can wait for a security fix before public disclosure + - label: I am requesting coordinated disclosure + - label: This has already been disclosed elsewhere + + - type: textarea + id: additional-info + attributes: + label: Additional Information + description: Any other relevant security information. + placeholder: | + Additional context: + - How did you discover this vulnerability? + - Are you aware of any exploitation in the wild? + - Any other relevant details? + validations: + required: false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..87e74d1 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,181 @@ +--- +name: Pull Request +about: Submit a pull request to improve tzst +title: '' +labels: '' +assignees: '' +--- + +## Summary + + + +## Type of Change + + + +- [ ] πŸ› Bug fix (non-breaking change that fixes an issue) +- [ ] ✨ New feature (non-breaking change that adds functionality) +- [ ] πŸ’₯ Breaking change (fix or feature that would cause existing functionality to change) +- [ ] πŸ“š Documentation update (changes to documentation only) +- [ ] πŸ§ͺ Test improvements (adding or updating tests) +- [ ] πŸ”§ Build/CI changes (changes to build process or CI configuration) +- [ ] ♻️ Refactoring (code changes that neither fix bugs nor add features) +- [ ] ⚑ Performance improvement +- [ ] πŸ”’ Security fix + +## Related Issues + + + + + + + +## Changes Made + + + +### Core Changes + +- + +### API Changes + +- + +### CLI Changes + +- + +## Testing + + + +### Test Coverage + +- [ ] Added tests for new functionality +- [ ] Updated existing tests as needed +- [ ] All tests pass locally (`python -m pytest`) +- [ ] Code coverage is maintained or improved + +### Manual Testing + +- [ ] Tested on Windows +- [ ] Tested on macOS +- [ ] Tested on Linux +- [ ] Tested with Python 3.12 +- [ ] Tested with Python 3.13 + +### Test Scenarios + +- +- +- + +## Code Quality + + + +- [ ] Code follows project style guidelines (`ruff check .`) +- [ ] Code is properly formatted (`ruff format --check .`) +- [ ] Type hints are added for new public APIs +- [ ] Docstrings are added/updated for public methods +- [ ] No new security vulnerabilities introduced + +## Documentation + + + +- [ ] README.md updated (if needed) +- [ ] CHANGELOG.md updated (for user-facing changes) +- [ ] Code comments added for complex logic +- [ ] Docstrings updated for modified functions/classes + +## Backwards Compatibility + + + +- [ ] Changes are backwards compatible +- [ ] Breaking changes are documented and justified +- [ ] Migration guide provided (if applicable) + +## Performance Impact + + + +- [ ] No performance regression +- [ ] Performance improvement (describe below) +- [ ] Performance impact assessed and documented + + + +## Security Considerations + + + +- [ ] No security implications +- [ ] Security review completed +- [ ] Input validation added/updated +- [ ] Secure defaults maintained + +## Platform Compatibility + + + +- [ ] Windows compatibility verified +- [ ] macOS compatibility verified +- [ ] Linux compatibility verified +- [ ] Cross-platform file path handling tested + +## Dependencies + + + +- [ ] No new dependencies added +- [ ] New dependencies are justified and minimal +- [ ] Dependency versions are appropriately constrained +- [ ] Optional dependencies are properly marked + +## Deployment + + + +- [ ] Version number updated (if applicable) +- [ ] Release notes prepared (if applicable) +- [ ] Migration steps documented (if applicable) + +## Checklist + + + +- [ ] PR title follows conventional commit format +- [ ] All CI checks are passing +- [ ] Code has been self-reviewed +- [ ] Changes have been tested thoroughly +- [ ] Documentation is complete and accurate +- [ ] Ready for code review + +## Additional Notes + + + +## Reviewer Notes + + + +### Review Focus Areas + +- +- +- + +### Questions for Reviewers + +- +- + +--- + + + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..8592a90 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,374 @@ +# Contributing to tzst + +Thank you for your interest in contributing to tzst! This document provides guidelines and information for contributors. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [Getting Started](#getting-started) +- [Development Setup](#development-setup) +- [Project Structure](#project-structure) +- [Making Changes](#making-changes) +- [Testing](#testing) +- [Code Style](#code-style) +- [Submitting Changes](#submitting-changes) +- [Release Process](#release-process) +- [Getting Help](#getting-help) + +## Code of Conduct + +This project follows the principles of respectful collaboration. Please be kind, constructive, and professional in all interactions. + +## Getting Started + +### Prerequisites + +- Python 3.12 or higher +- Git +- Basic knowledge of tar archives and compression + +### Development Setup + +1. **Fork and clone the repository:** + + ```bash + git clone https://github.com/your-username/tzst.git + cd tzst + ``` + +2. **Create a virtual environment:** + + ```bash + python -m venv venv + # On Windows + venv\Scripts\activate + # On Unix/macOS + source venv/bin/activate + ``` + +3. **Install the package in development mode:** + + ```bash + pip install -e .[dev] + ``` + +4. **Verify the installation:** + + ```bash + python -m pytest tests/ + ``` + +## Project Structure + +``` +tzst/ +β”œβ”€β”€ src/tzst/ # Main package source code +β”‚ β”œβ”€β”€ __init__.py # Package initialization and exports +β”‚ β”œβ”€β”€ __main__.py # CLI entry point +β”‚ β”œβ”€β”€ cli.py # Command-line interface +β”‚ β”œβ”€β”€ core.py # Core archive functionality +β”‚ └── exceptions.py # Custom exceptions +β”œβ”€β”€ tests/ # Test suite +β”‚ β”œβ”€β”€ conftest.py # Pytest configuration and fixtures +β”‚ β”œβ”€β”€ test_core.py # Core functionality tests +β”‚ β”œβ”€β”€ test_cli.py # CLI tests +β”‚ └── test_*.py # Additional test modules +β”œβ”€β”€ .github/ # GitHub workflows and templates +β”œβ”€β”€ pyproject.toml # Project configuration +β”œβ”€β”€ README.md # Project documentation +β”œβ”€β”€ LICENSE # BSD 3-Clause License +└── CONTRIBUTING.md # This file +``` + +## Making Changes + +### Types of Contributions + +We welcome various types of contributions: + +- **Bug fixes**: Fix issues in existing functionality +- **Features**: Add new capabilities to the library +- **Documentation**: Improve or add documentation +- **Tests**: Add or improve test coverage +- **Performance**: Optimize existing code +- **Security**: Address security vulnerabilities + +### Branch Naming + +Use descriptive branch names: + +- `feature/add-streaming-mode` +- `fix/handle-corrupted-archives` +- `docs/improve-api-documentation` +- `test/add-compression-tests` + +### Commit Messages + +Follow conventional commit format: + +``` +type(scope): description + +[optional body] + +[optional footer] +``` + +Types: + +- `feat`: New feature +- `fix`: Bug fix +- `docs`: Documentation changes +- `test`: Adding or modifying tests +- `refactor`: Code refactoring +- `perf`: Performance improvements +- `chore`: Build process or auxiliary tool changes + +Examples: + +``` +feat(core): add streaming compression support + +fix(cli): handle invalid archive paths gracefully + +docs(readme): update installation instructions +``` + +## Testing + +### Running Tests + +```bash +# Run all tests +python -m pytest + +# Run with coverage +python -m pytest --cov + +# Run specific test file +python -m pytest tests/test_core.py + +# Run with verbose output +python -m pytest -v + +# Run integration tests only +python -m pytest -m integration +``` + +### Test Structure + +- Unit tests: Test individual functions and methods +- Integration tests: Test component interactions +- CLI tests: Test command-line interface +- Platform-specific tests: Test OS-specific functionality + +### Writing Tests + +1. **Use descriptive test names:** + + ```python + def test_create_archive_with_compression_level_9(): + ``` + +2. **Use fixtures for common test data:** + + ```python + def test_extract_archive(sample_archive_path, temp_dir): + ``` + +3. **Test edge cases:** + - Empty files + - Large files + - Invalid inputs + - Corrupted archives + +4. **Add markers for test categorization:** + + ```python + @pytest.mark.integration + def test_full_archive_workflow(): + ``` + +## Code Style + +This project uses [Ruff](https://docs.astral.sh/ruff/) for linting and formatting. + +### Configuration + +Settings are defined in `pyproject.toml`: + +- Line length: 88 characters +- Target Python version: 3.12+ +- Import sorting with isort +- Quote style: double quotes + +### Running Code Style Tools + +```bash +# Check code style +ruff check . + +# Fix auto-fixable issues +ruff check --fix . + +# Format code +ruff format . + +# Check formatting without making changes +ruff format --check . +``` + +### Code Style Guidelines + +1. **Follow PEP 8** with project-specific modifications +2. **Use type hints** for all public APIs +3. **Write docstrings** for classes and public methods +4. **Keep functions focused** and reasonably sized +5. **Use meaningful variable names** +6. **Add comments** for complex logic + +### Documentation Strings + +Use Google-style docstrings: + +```python +def create_archive( + archive_path: str | Path, + files: Sequence[str | Path], + compression_level: int = 3, +) -> None: + """Create a new tzst archive containing the specified files. + + Args: + archive_path: Path where the archive will be created. + files: Sequence of file/directory paths to include. + compression_level: Zstandard compression level (1-22). + + Raises: + TzstArchiveError: If archive creation fails. + FileNotFoundError: If input files don't exist. + """ +``` + +## Submitting Changes + +### Pull Request Process + +1. **Create a feature branch:** + + ```bash + git checkout -b feature/your-feature-name + ``` + +2. **Make your changes** following the guidelines above + +3. **Add tests** for new functionality + +4. **Update documentation** if needed + +5. **Run the test suite:** + + ```bash + python -m pytest + ruff check . + ruff format --check . + ``` + +6. **Commit your changes:** + + ```bash + git add . + git commit -m "feat: add your feature description" + ``` + +7. **Push to your fork:** + + ```bash + git push origin feature/your-feature-name + ``` + +8. **Create a pull request** using the provided template + +### Pull Request Guidelines + +- **Fill out the PR template** completely +- **Link related issues** using keywords (fixes #123) +- **Keep PRs focused** - one feature/fix per PR +- **Update CHANGELOG.md** for user-facing changes +- **Ensure all CI checks pass** +- **Respond to review feedback** promptly + +### Review Process + +1. Automated checks must pass (CI/CD, code style) +2. Code review by maintainers +3. Address any feedback or requested changes +4. Final approval and merge by maintainers + +## Release Process + +Releases are handled by maintainers: + +1. Update version in `src/tzst/__init__.py` +2. Update `CHANGELOG.md` +3. Create a release tag +4. Automated CI/CD publishes to PyPI + +## Getting Help + +### Resources + +- **Issues**: [GitHub Issues](https://github.com/xixu-me/tzst/issues) +- **Discussions**: Use GitHub Discussions for questions +- **Documentation**: Check the README and code comments + +### Reporting Issues + +When reporting bugs: + +1. **Use the bug report template** +2. **Provide a minimal reproduction case** +3. **Include system information** (OS, Python version) +4. **Attach relevant files** if possible (archives, logs) + +### Suggesting Features + +When suggesting features: + +1. **Use the feature request template** +2. **Explain the use case** and motivation +3. **Consider backwards compatibility** +4. **Provide implementation ideas** if you have them + +## Development Tips + +### Performance Considerations + +- Use streaming for large files +- Consider memory usage patterns +- Profile code for bottlenecks +- Test with various file sizes + +### Security Considerations + +- Validate all user inputs +- Use secure defaults (e.g., 'data' filter) +- Handle malicious archives safely +- Be cautious with file paths + +### Compatibility + +- Support Python 3.12+ +- Test on multiple platforms (Windows, macOS, Linux) +- Consider different filesystem behaviors +- Maintain backwards compatibility when possible + +## Recognition + +Contributors are recognized in several ways: + +- Listed in release notes for significant contributions +- Mentioned in README acknowledgments +- GitHub contributor statistics + +Thank you for contributing to tzst! Your efforts help make this library better for everyone. diff --git a/src/tzst/__init__.py b/src/tzst/__init__.py index 585dff9..a04a123 100644 --- a/src/tzst/__init__.py +++ b/src/tzst/__init__.py @@ -1,6 +1,6 @@ """tzst - A Python library for creating and manipulating .tzst/.tar.zst archives.""" -__version__ = "1.0.1" +__version__ = "1.0.0" from .core import ( TzstArchive,