Skip to content

Latest commit

 

History

History
362 lines (284 loc) · 14 KB

CONTRIBUTING.md

File metadata and controls

362 lines (284 loc) · 14 KB
Raw

Contributing to DynaDojo

Getting Started

Prerequisites

  • Python (v3.10 or greater). We recommend using mise (or pyenv) for Python version management.
  • PDM (v.2.15.4) for package management and for python environments.

Additional System Requirements

Optional Package: The project can optionally depend on TensorFlow 2 for certain functionalities. Please refer to Tensorflow 2 install for any system requirements.

Recommended Setup

  1. For MacOS:

    1. Install xcode tools: xcode-select --install
    2. Install homebrew: Follow the instructions on brew

  2. Install mise/pyenv: Follow the instructions on mise website or pyenv GitHub page.

    1. mise (Recommended): For macOS,

      brew install mise
echo '\neval "$(mise activate zsh)"\n' >> ~/.zshrc
exec "$SHELL" #restart shell

      Otherwise see mise documentation

    2. pyenv: For macOS, see steps 1-5 here Otherwise see pyenv documentation

  3. Install Python 3.10

    1. using mise (Recommended): 
      mise use [email protected]
    2. using pyenv: 
      pyenv install 3.10.14
pyenv shell 3.10.14   #use the newly installed version

    Check your installation by running which python which should output something along the lines of:

    • for mise: /Users/[user]/.local/share/mise/installs/python/3.10.14/bin/python

    • for pyenv: /Users/[user]/.pyenv/shims/python

    If there are issues with your installation, check your echo $PATH variable for any other python installations. Remove them from ~/.zshrc and ~/.zprofile for ZSH (or ~/.bashrc and ~/.bash_profile) for BASH.

  4. Install pdm:

    1. using mise (Recommended):

      Installing via mise will allow for the flexibilty to change pdm versions depending on the project.

       mise use --global [email protected]

    2. For macOS, with brew:

      brew install pdm

    3. Otherwise, see pdm documentation.

  5. Fork the Repository: Fork the repository on GitHub by clicking the "Fork" button on the repository's page. This creates a copy of the code under your GitHub user account

  6. Clone your forked repository:

    git clone https://github.com/your-username/dynadojo.git
cd dynadojo

  7. Add the Dynadojo upstream remote to your local Dynadojo clone:

    git remote add upstream https://github.com/DynaDojo/dynadojo.git

  8. Configure git to pull main from the upstream remote:

git switch main # ensure you're on the main branch
git fetch upstream --tags
git branch --set-upstream-to=upstream/main

  1. Set python version:

    1. mise (Recommended):

      echo 3.10.14 > .python-version

    2. pyenv:

      pyenv local 3.10.14 # set the default python version in current folder

  2. Install Dynadojo dependencies:

    pdm install -G all

    If installation fails, please delete pdm.lock and try again.

    1. Optional: Install additional optional dependencies: 
      pdm add -G [optional package]
      For Macs with Apple Silicon, you might want to add tensorflow-mac for Mac GPU support when running tensorflow. Please check Apple for system requirements.

  3. Reload your terminal to activate the pdm venv. or run

$(pdm venv activate)
  1. Check your python path:
which python # should be [path to project]/DynaDojo/.venv/bin/python

Making Changes

  1. Make sure you're on the main branch.

    git switch main

  2. Use the git pull command to retrieve content from the DynaDojo Github repository.

    git pull

  3. Create a new branch and switch to it.

    git switch -c a-descriptive-name-for-my-changes

    Please use branch naming conventions. See branch naming section below.

  4. Make your changes!

  5. Use the git add command to save the state of files you have changed.

    git add <names of the files you have changed>

  6. Commit your changes.

    git commit

    Please remember to write good commit messages

  7. Rebase on upstream/main to keep your fork of the code up to date with the original repository.

    git fetch upstream
git rebase upstream/main

    Resolve any conflicts, test your code, commit.

  8. Push all changes to your fork of dynadojo (origin) on GitHub.

    git push -u origin a-descriptive-name-for-my-changes

    You may have to push with the --force flag.

  9. Click on Pull Request on Github to open a pull request. Make sure you tick off all the boxes on our checklist below. When you're ready, you can send your changes to the project maintainers for review. Once approved please squash commits and merge.

Branch Naming

Please follow the convention of [prefix]/[description]/[optional issue #]/[optional name]``. So for example feat/transformer/carynorbug/plotting/100`

Guidelines:

  • Lowercase and Hyphen-separated: Stick to lowercase for branch names and use hyphens to separate words.
    • For instance, feature/new-login or bugfix/header-styling.
  • Alphanumeric Characters: Use only alphanumeric characters (a-z, 0–9) and hyphens. Avoid punctuation, spaces, underscores, or any non-alphanumeric character.
  • No Continuous Hyphens: Do not use continuous hyphens. feature--new-login can be confusing and hard to read.
  • No Trailing Hyphens: Do not end your branch name with a hyphen. For example, feature-new-login- is not a good practice.
  • Descriptive: The name should be descriptive and concise, ideally reflecting the work done on the branch.

Branch Prefixes

Using prefixes in branch names helps to quickly identify the purpose of the branches. Here are some types of branches with their corresponding prefixes:

  • Feature Branches: These branches are used for developing new features.
    • Use the prefix feat/. For instance, feat/login-system.
  • Bug fix Branches: These branches are used to fix bugs in the code.
    • Use the prefix bug/. For example, bug/header-styling.
  • Release Branches: These branches are used to prepare for a new production release. They allow for last-minute dotting of i’s and crossing t’s.
    • Use the prefix release/. For example, release/v1.0.1.
  • Documentation Branches: These branches are used to write, update, or fix documentation.
    • Use the prefix docs/. For instance, docs/api-endpoints.
  • Experiment Branches: These branches are used for running experiments.
    • Use the prefix exp/. For instance, exp/neural-ode
  • Works-in-Progress Branches: These branches are for projects that won't be completed any time soon.
    • Use the prefix wip/.
  • Junk Branches: Throwaway branch.
    • Use the prefix junk/.

Pull request checklist

  • The pull request title should summarize your contribution and should start with one of the following prefixes:
    • feat: (new feature for the user, not a new feature for build script)
    • fix: (bug fix for the user, not a fix to a build script)
    • docs: (changes to the documentation)
    • style: (formatting, missing semicolons, etc; no production code change)
    • refactor: (refactoring production code, eg. renaming a variable)
    • perf: (code changes that improve performance)
    • test: (adding missing tests, refactoring tests; no production code change)
    • chore: (updating grunt tasks etc; no production code change)
    • build: (changes that affect the build system or external dependencies)
    • ci: (changes to configuration files and scripts)
    • revert: (reverts a previous commit)
    • Example: "feat: add support for PyTorch".
    • Note: This is based on the Conventional Commits specification
  • If your pull request addresses an issue, please mention the issue number in the pull request description and title to make sure they are linked (and people viewing the issue know you are working on it).
  • To indicate a work in progress please prefix the title with [WIP]. These are useful to avoid duplicated work, and to differentiate it from PRs ready to be merged.
  • Make sure existing tests pass.
  • If adding a new feature, also add tests for it.
  • All public methods must have informative docstrings.

Running Tests

pdm run python -m unittest