Skip to content

Coding Guidelines#

biocommons projects use shared technical and coding conventions in order to operate consistently and coherently, and to facilitate contributors moving between projects.

General Guidelines#

  • Create issues for proposed changes. Most development should be the result of a bug or feature issue. Discuss major changes there. This will help coordinate work that might duplicate or conflict with others.

  • New developers work in forks. New contributors should work in their own forks. Frequent contributors may ask for write permissions on relevant repos to increase community awareness of their work.

  • Submit changes as a pull request. Code owners may commit directly with discretion, but this should be rare. Follow GitHub Guidance to title PRs like "Fixes #123: File not found when..." or "Closes #456: Implement sequence caching".

  • Link branches to issues and follow the branch naming convention. Follow GitHub instructions for linking a branch with an issue. Use branch names like 123-implement-some-feature.

  • Contributors should squash commits before submitting a PR if they wish to do so. Squash on PR merge is disabled because it leaves dangling branches, and because cleanup should be a contributor responsibility. See tip below for how to squash a branch, including one that you've already pushed.

  • Strive for consistency within and across projects unless you have a very good reason to do otherwise.

  • Keep PRs focused on a single issue. PRs that mix multiple goals are hard to read and evalutate. Strive for PRs that result in atomic commits. For example, don't refactor/restructure/reformat code while implementating a feature; instead, separate those goals into distinct PRs.

  • Strive for DRYness (Don't Repeat Yourself).

  • PRs should include tests and documentation. Test your code before committing. Tests must pass before merging.

  • Use Semantic Versioning. Package versions are derived from git tags in order to ensure that released software always corresponds to a git tag. We don't use a "v" prefix.

  • All source code is licensed under the Apache License, 2.0.

  • Use existing case conventions

    Convention Description Examples
    ALL_CAPS Used for constants. PI, MAX_SIZE
    snake_case Used for functions, variables, and methods. my_function, my_variable
    PascalCase Used for class names. Abbreviations are kept all-caps. MyClass, RESTClient
    _single_leading_us Entitu is for internal use only. Should not be accessed directly by other modules. _internal_variable, _logger
    __double_leading_us Class quasi-private variable. The name is automatically rewritten by the interpreter to avoid conflicts in subclasses. __private_variable
    single_trailing_us_ To avoid conflict with Python keywords. class_, type_
    __double_lead_and_trail_us__ "Magic" or "dunder" methods. Indicate special methods or attributes in Python. Rarely defined in bicommons. __init__, __str__

Python-specific guidelines#

  • We test and support at least the three most recent full Python releases at any point it time. We might test and advertise broader availability on a repo-by-repo basis. However, we never want current development to be limited by a stale version of Python.

  • Packages must be based on the biocommons.example repo. Updates to this template will occasionally be merged into the repos.

  • Don't catch exceptions unless you expect to respond meaningfully. Mostly it helps to learn to just let it go, just like Elsa.

  • Configuration: config env vars should be high in the stack, adjacent to other configuration, and passed down. Env vars should typically not change behavior deep in a call stack. In no circumstance should an env var override an explicit setting higher in the stack. Debugging, logging, and other observability tooling are exceptions to this rule.

Tips#

How can I checkout a branch on the command line using the preferred branch name format?#

» gh issue develop 24 -c   # create branch for issue 24 and check it out 
github.com/biocommons/biocommons.github.io/tree/24-create-adr-repo-and-template

How can I easily squash commits on a branch before submitting a PR?#

The general solution is to use git rebase, which replays commits on one branch onto another. Try this:

» git checkout your-branch
» git reset --soft main          # main is the parent branch name
» git commit -m "Closes #42: A massive feature (squashed commits for readability)"
» git push --force-with-lease    # force is required if you've already pushed the branch

Please use --force-with-lease, which provides additional checks to ensure that your branch is up to date. It will keep you from overwriting your colleague's changes.

Future Work: Topics to Write#

  • Branch, merge, and release strategy, with tradeoffs and considerations
  • Release process, including changelogs
  • vscode setup: common extensions, devcontainers, formatters
  • sample coding session: issue, branch, code, test, format, push, request PR, merge
  • semantic release
  • commit message formats