Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
247 lines (211 loc) · 5.66 KB

DEVELOPMENT.md

File metadata and controls

247 lines (211 loc) · 5.66 KB

Development

This is an example workflow describing the development process for EasyScience projects.

🚀 Step 1: Create GitHub Repositories

Required repositories

  • project-name (home repository, always)
  • project-name-lib (for Python libraries, optional)
  • project-name-app (for Qt QML desktop applications, optional)

🛠️ Step 2: Initialize Projects Using Copier

Clone repositories

  • Clone all project-related repositories: 
    git clone https://github.com/easyscience/dynamics.git
git clone https://github.com/easyscience/dynamics-lib.git
git clone https://github.com/easyscience/dynamics-app.git

Install Pixi

Generate Project Description (Home Repository)

  • Navigate to the home repository: 
    cd dynamics
  • Set up Pixi and Copier: 
    pixi init
pixi install
pixi add copier
  • Generate project description: 
    pixi run copier copy gh:easyscience/templates .
  • Commit and push: 
    git add -A
git commit -m "Initial project description using Copier"
git push origin master
  • Navigate back to the parent directory: 
    cd ..

Apply Templates to Library / Application Repositories

  • Navigate to the target repository: 
    cd dynamics-lib
  • Set up Pixi and Copier: 
    pixi init
pixi install
pixi add copier
  • Apply templates (shared and library-specific): 
    pixi run copier copy gh:easyscience/templates-shared . --data-file ../dynamics/.project.yaml
pixi run copier copy gh:easyscience/templates-lib . --data-file ../dynamics/.project.yaml
  • Install development dependencies: 
    pixi run post-install
  • Copy logos and branding into docs/: 
    pixi run docs-update-assets
  • Update SPDX license headers in all files: 
    pixi run spdx-update
  • Format Python and non-Python files: 
    pixi run fix
  • Commit and push: 
    git add -A
git commit -m "Initial project setup using Copier templates"
git push origin master
  • Navigate back to the parent directory: 
    cd ..

🛡️ Step 3: Post-Initialization Repository Setup

  • Create and publish develop branch: 
    git checkout -b develop
git push -u origin develop
  • The gh-pages branch is created automatically by GitHub Action docs.yaml (using mike when deploying docs)
  • Set branch protection rules for master (default), develop, and gh-pages

🔄 Step 4: Updating Existing Repositories

When templates change, repositories must be updated.

  • Apply updates from shared templates, if any: 
    pixi run copier-update-shared
  • Commit changes
  • Apply updates from library templates, if any: 
    pixi run copier-update-lib
  • Commit changes

Step 5: Making and Pushing Changes

Create a new feature branch

  • Checkout/switch to the develop branch: 
    git checkout develop
  • Create a new branch from develop: 
    git checkout -b new-feature
  • Push the new branch to the remote repository: 
    git push -u origin new-feature

Commit and push changes

Make incremental changes in the code, checking code quality and testing.

Pre-commit checks

  • Check code quality (configuration is in pyproject.toml and prettierrc.toml): 
    pixi run pre-commit-check
  • Fix some code quality issues automatically: 
    pixi run fix
  • Fix the rest, if any, manually
  • Commit changes

Pre-push checks

  • Run tests and checks before pushing changes: 
    pixi run pre-push
  • Fix issues, if any, manually
  • Push changes

Individual tests and checks (as needed)

  • Run unit tests: 
    pixi run unit-tests
  • Run integration tests: 
    pixi run integration-tests
  • Test tutorials as Python scripts: 
    pixi run script-tests

Test and docstring coverage (as needed)

  • Check docstring coverage: 
    pixi run docstring-coverage
  • Run unit tests with coverage: 
    pixi run unit-tests-coverage
  • Run integration tests with coverage: 
    pixi run integration-tests-coverage
  • Or just run them all sequentially: 
    pixi run cov

Building and Checking Documentation with MkDocs (as needed)

  • Prepare notebooks: 
    pixi run notebook-prepare
  • Build and serve documentation: 
    pixi run docs-serve
  • Test the documentation locally (built in the site/ directory). E.g., on macOS, open the site in the default browser via the terminal: 
    open http://127.0.0.1:8000

Step 6: Create a Pull Request

When everything is implemented, and once all CI checks are finished and green at dynamics-lib or dynamics-app.

  • Create a pull request on the dynamics-lib or dynamics-app and request a review from team members.
  • When making a title for the PR, keep in mind that this title will be used in autogenerated release notes.
  • Add one of the required labels (needed for automatic version bumps and categories in autogenerated release notes):
    • [scope] bug
    • [scope] documentation
    • [scope] enhancement
    • [scope] maintenance
    • [scope] significant
  • After approval, merge the pull request into the develop branch using "Squash and merge" option
  • Delete the branch remotely: 
    git push origin --delete new-feature