Merge pull request #92 from UBC-MDS/otter

Create release 3.0.0

Author: sgauth01

.github/workflows/build.yml

@@ -57,4 +57,9 @@ jobs:
 
       - name: Run tests with coverage
         run: |
-          pytest --cov --cov-report=term --cov-branch
+          pytest --cov --cov-branch --cov-report=xml
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v5
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/deploy.yml

@@ -1,10 +1,10 @@
 name: Publish to TestPyPI
 
 on:
+  workflow_dispatch:
   push:
-    branches:
-      - main
-  workflow_dispatch: # Manual trigger
+    tags:
+      - '*.*.*'
 
 jobs:
   build-and-test:

.github/workflows/docs-preview.yml

@@ -0,0 +1,88 @@
+on:
+  workflow_dispatch:
+  pull_request:
+    branches: [ main, otter ]
+
+name: Preview Documentation
+
+jobs:
+  render-docs-preview-deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      deployments: write
+      pull-requests: write
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Quarto
+        uses: quarto-dev/quarto-actions/setup@v2
+
+      # Set up Python
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: '3.13'
+
+      # Install dependencies
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[docs]
+
+      # manually call quartodoc build
+      - name: quartodoc build
+        run: |
+          quartodoc build
+
+      - name: Render Quarto Project
+        uses: quarto-dev/quarto-actions/render@v2
+
+      # =====================================================
+      # Deploy to Netlify
+      # =====================================================
+
+      # Create a unique name for this deployment using the PR number
+      # This helps track which PR preview is which
+      - name: Configure release name
+        run: echo "RELEASE_NAME=pr-${{ github.event.number }}" >> $GITHUB_ENV
+
+      # Create a deployment status on GitHub to track the deployment progress
+      # This shows up in the PR's "Deployments" section
+      - name: Create deployment status
+        uses: bobheadxi/deployments@v1
+        id: deployment
+        with:
+          step: start
+          token: ${{ secrets.GITHUB_TOKEN }}
+          env: ${{ env.RELEASE_NAME }}
+          ref: ${{ github.head_ref }}
+          logs: 'https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}'
+
+      # Deploy the rendered site to Netlify with a PR-specific preview URL
+      # The alias ensures each PR gets its own stable URL during review
+      - name: Deploy to Netlify
+        id: netlify
+        env:
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+        run: |
+          npm install -g netlify-cli
+          netlify deploy --dir=_site/ --alias="pr-${{ github.event.number }}" 2>&1 | tee deploy.log
+          DEPLOY_URL=$(grep -oP 'https://[^\s]+' deploy.log | grep -E '(netlify\.app|--.*\.netlify\.app)' | head -n 1)
+          echo "url=${DEPLOY_URL}" >> $GITHUB_OUTPUT
+          
+      # Update the GitHub deployment status with success/failure and the preview URL
+      # This creates a clickable link in the PR to view the deployed preview
+      - name: Update deployment status
+        uses: bobheadxi/deployments@v1
+        if: always()
+        with:
+          step: finish
+          token: ${{ secrets.GITHUB_TOKEN }}
+          status: ${{ job.status }}
+          deployment_id: ${{ steps.deployment.outputs.deployment_id }}
+          env: ${{ steps.deployment.outputs.env }}
+          env_url: ${{ steps.netlify.outputs.url }}
+          logs: 'https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}'

CHANGELOG.md

@@ -58,3 +58,17 @@ All notable changes to this project will be documented in this file.
 - Removed unused `docs` directory and Sphinx configuration
 - Removed unused GitHub Actions workflows
 - Removed Sphinx-related dependencies from `pyproject.toml`
+
+## [3.0.0] - 2026-02-02
+
+- Fixed errors when running examples in `README.md` and docstrings (with many thanks to the peer review)
+- Added step-by-step tutorials to `README.md` and documentation site (with many thanks to the peer review)
+- Added `CHANGELOG.md` to the documentation site
+- Added badges to `README.md` for PyPI version, build status, code quality, and documentation status
+- Added more words to `minidict` dataset
+- Added more in-line comments to user functions (with many thanks to the peer review)
+- Added work organization and retrospectives to `CONTRIBUTING.md`
+- Added GitHub Actions workflow for dynamic versioning
+- Added GitHub Actions workflow for previewing documentation site
+- Added GitHub Actions workflow for code coverage reporting
+- Removed redundant signs in the example code snippets in `README.md` (with many thanks to the peer review)

CONTRIBUTING.md

@@ -111,6 +111,158 @@ Before you submit a pull request, check that it meets these guidelines:
 
 Your suggested code should follow [PEP 8](https://pep8.org/) Python style guide. We recommend [Ruff](https://docs.astral.sh/ruff/) for automatic code formatting and linting. Use straightforward variable names and keep functions focused on one single task. Docstrings need to be documented under all functions and classes definitions using [NumPy style](https://peps.python.org/pep-0008/#documentation-strings).
 
+## Development Tools and Infrastructure
+
+This section documents the development tools, GitHub infrastructure, and organizational practices applied in this project, as well as considerations for scaling up similar projects.
+
+### Tools Used in This Project
+
+#### Package Management and Build Tools
+
+- **Hatch**: Modern Python project manager for building, versioning, and environment management
+  - Simplifies dependency management and virtual environment creation
+  - Provides consistent build and test workflows on deploying package
+- **Conda**: Cross-platform package and environment manager
+  - Manages project dependencies and isolated environments
+  - Facilitates reproducible development setups
+
+#### Code Quality and Testing
+
+- **pytest**: Testing framework for writing and running unit tests
+  - Comprehensive test coverage in `tests/` directory
+  - Enables test-driven development practices
+- **Codecov**: Code coverage reporting tool
+  - Tracks test coverage percentage
+  - Identifies untested code paths
+- **Ruff**: Python linter and code formatter
+  - Enforces code style and quality standards
+  - Automatically formats code to adhere to PEP 8 guidelines
+
+#### Documentation
+
+- **Quarto**: Scientific and technical publishing system
+  - Generates project documentation from markdown and code
+  - Integrates narrative text with executable code examples
+- **quartodoc**: Quarto extension for documentation sites
+  - Provides templates and tools for building documentation websites
+- **NumPy-style docstrings**: Standard documentation format
+  - Provides clear, structured documentation for all functions
+  - Enables automatic documentation generation
+
+#### Version Control
+
+- **Git**: Distributed version control system
+- **GitHub**: Cloud-based repository hosting and collaboration platform
+
+### GitHub Infrastructure
+
+Our project leverages several GitHub features for collaboration and automation:
+
+#### Repository Organization
+
+- **Branching Strategy**: Feature branch workflow
+  - `main` branch for stable code
+  - `otter` branch as our dev branch to integrate features, bug fixes, and changes before they are ready for production
+  - `gh-pages`: Branch for hosting documentation site
+  - Pull requests for merging changes into `main` or `otter`
+
+#### Issue Tracking
+
+- **GitHub Projects**: Kanban boards for task tracking
+  - Backlog management and roadmap visualization
+  - Allow tracking issues, pull requests, and ideas across customizable columns
+- **Issue Templates**: Standardized formats for bug reports and feature requests
+  - Ensures comprehensive information collection
+  - Streamlines triage and prioritization
+
+#### Pull Request Workflow
+
+- **Pull Request Templates**: Guide contributors through necessary information
+- **Code Review**: Copilot and peer review process before merging
+- **Automated Checks**: CI/CD integration validates code quality
+
+#### Project Documentation
+
+- **README.md**: Project overview, installation, and usage instructions
+- **CONTRIBUTING.md**: Contribution guidelines and development setup
+- **CODE_OF_CONDUCT.md**: Community standards and expectations
+- **CHANGELOG.md**: Record of changes and version history
+- **LICENSE**: MIT License for open-source distribution
+
+### Organizational Practices
+
+#### Development Workflow
+
+- **Issue-Driven Development**: All changes start with an issue
+- **Test-Driven Development**: Write tests before implementing features
+- **Code Review**: All changes reviewed by at least one team member
+
+#### Team Collaboration
+
+- **Clear Ownership**: Issues assigned to specific team members
+- **Communication**: GitHub issues and pull requests for async collaboration
+- **Documentation**: Comprehensive inline comments and docstrings
+- **Consistency**: Shared code style and formatting standards
+
+#### Quality Assurance
+
+- **Type Hints**: Python type annotations throughout codebase
+- **Unit Tests**: Comprehensive test coverage in `tests/unit/`
+- **Manual Testing**: Verification of functionality before merging
+
+### Scaling Up: Tools and Practices for Larger Projects
+
+If scaling this or similar projects, we would implement the following additional tools and practices:
+
+#### Continuous Integration/Continuous Deployment (CI/CD)
+
+- **GitHub Actions**: Automate testing, building, and deployment
+  - Run test suite on every push and pull request
+  - Automatic package building and publishing to PyPI
+  - Documentation deployment to GitHub Pages or Read the Docs
+- **Pre-commit Hooks**: Enforce code quality locally before commits
+  - Check for large files, merge conflicts, and trailing whitespace
+
+#### Enhanced Testing
+
+- **Performance Tests**: Ensure functions maintain acceptable performance
+- **Integration Tests**: Test component interactions
+- **End-to-End Tests**: Validate complete workflows
+
+#### Dependency Management
+
+- **Dependabot**: Automated dependency updates
+  - Security vulnerability notifications
+  - Automatic pull requests for updates
+- **Safety/Bandit**: Security scanning for vulnerabilities
+- **Lock Files**: Pin exact dependency versions for reproducibility
+
+#### Code Quality Tools
+
+- **MyPy**: Static type checking
+  - Catch type errors before runtime
+  - Improve code reliability
+- **Coverage Requirements**: Enforce minimum coverage thresholds
+- **SonarQube/CodeClimate**: Advanced code quality metrics
+  - Code complexity analysis
+  - Maintainability scoring
+  - Security hotspot detection
+
+#### Project Management
+
+- **Issue Automation**: Automated labeling and triage
+- **Release Management**: Semantic versioning with automated releases
+
+#### Monitoring and Analytics
+
+- **PyPI Statistics**: Track package downloads and usage
+- **Error Tracking**: Sentry or similar for runtime error monitoring
+- **User Feedback**: Issue templates for user-reported bugs and features
+
+### Conclusion
+
+The tools and practices applied in this project establish a solid foundation for collaborative open-source development. For larger-scale projects, the additional infrastructure focuses on automation, quality assurance, and enabling distributed teams to work effectively. The key principle is to automate routine tasks, enforce quality standards early in the development process, and maintain clear documentation and communication channels.
+
 ## Code of Conduct
 
 Please not that this project is released with a [Contributor Code of Conduct](CODE_OF_CONDUCT.md). By participating in this project you agree to abide by its terms.

README.md

@@ -2,8 +2,10 @@
 
 |        |        |
 |--------|--------|
-| Package | [![Latest PyPI Version](https://img.shields.io/pypi/v/wordguess.svg)](https://pypi.org/project/wordguess/) [![Supported Python Versions](https://img.shields.io/pypi/pyversions/wordguess.svg)](https://pypi.org/project/wordguess/)  |
-| Meta   | [![Code of Conduct](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](CODE_OF_CONDUCT.md) |
+| Package | [![Latest Test PyPI Version](https://img.shields.io/pypi/v/wordguess?label=TestPyPI&logo=python&color=blue&pypiBaseUrl=https%3A%2F%2Ftest.pypi.org)](https://test.pypi.org/project/wordguess/) [![Supported Python Versions](https://img.shields.io/badge/python->=3.10-blue?logo=python)](https://test.pypi.org/project/wordguess/)  |
+| Meta   | [![Code of Conduct](https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg)](CODE_OF_CONDUCT.md) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+|Testing |[![Unit Tests](https://github.com/UBC-MDS/wordguess/actions/workflows/build.yml/badge.svg)](https://github.com/UBC-MDS/wordguess/actions/workflows/build.yml) [![codecov](https://codecov.io/github/UBC-MDS/wordguess/graph/badge.svg?token=wxpY8GJ0LI)](https://codecov.io/github/UBC-MDS/wordguess) |
+| Documentation|[![Docs Build](https://github.com/UBC-MDS/wordguess/actions/workflows/docs.yml/badge.svg)](https://github.com/UBC-MDS/wordguess/actions/workflows/docs.yml) |
 
 Wordguess is a project that contains essential functions for a word-guessing game, inspired by [Wordle](https://www.nytimes.com/games/wordle/index.html).
 
@@ -26,22 +28,40 @@ You can install this package into your preferred Python environment using pip:
 
 ```bash
 pip install -i https://test.pypi.org/simple/ wordguess
-``````
+```
+
+To use `wordguess` in your code, you can follow this full example that applies the built-in `minidict` dataset and all four main functions:
+
+```python
+# 1. Load the package with alias.
+import wordguess as wg
+```
 
-To use `wordguess` in your code:
+```python
+# 2. Get the string results of making three different guesses against the target "major". 
+result_hist = {}
+for word in ['whelp','might','madam']:
+    # As a player, we do not know the target word "major", 
+    # so we simulate getting the result:
+    result_hist[word] = wg.get_result('major', word)
+```
+
+```python
+# 3. Get the top three possible target words based on the result history. 
+# This may be used to provide hints to the player.
+wg.get_n_guesses(result_hist, n=3)
+```
 
 ```python
->>> from wordguess.get_result import get_result
->>> get_result("spark", "spoon")
+# 4. Get the overall score of guesses based on the results:
+results = list(result_hist.values())
+wg.get_score(results)
 ```
 
 ```python
->>> import wordguess as wg
->>> 
->>> result_hist = {}
->>> for word in ['whelp','might','madam']:
->>>     result_hist[word] = wg.get_result('major', word)
->>>     wg.get_n_guesses(result_hist, n=10)
+# 5. Convert the result of the last guess into a human-readable pattern.
+last_result = result_hist['madam']
+wg.result_to_pattern(last_result)
 ```
 
 ## Development

_quarto.yml

@@ -5,6 +5,7 @@ project:
     - LICENSE
     - CODE_OF_CONDUCT.md
     - CONTRIBUTING.md
+    - CHANGELOG.md
     - README.md
 
 website:
@@ -35,6 +36,8 @@ website:
         href: index.qmd
       - text: "API Reference"
         href: reference/index.qmd
+      - text: "Changelog"
+        href: CHANGELOG.md
       - text: "Contributing Guide"
         href: CONTRIBUTING.md
       - text: "Code of Conduct"