Skip to content

Onboarding Guide

Jump to bottom
James edited this page Jun 29, 2018 · 9 revisions

Onboarding Guide

The gnpy and gnpy-core projects are part of the Open Optical Packet Transport project group under the Telecom Infra Project. This project is lead by the Physical Layer Simulation Environment (PSE) working group.

The gnpy and gnpy-core repos seek to develop high-quality, community-driven open source tools for Guassian Noise modelling of amplified optical links.

This is the onboarding guide for new code contributors to the gnpy and gnpy-core code repositories.

Overall Philosophy

As part of the working group developing gnpy and gnpy-core, we will:

  • deliver high quality open-source software
  • driven by a community of both optical engineering and software development experts
  • developed using industry-standard software development practices

We measure our success in developing software along these lines by the ease of onboarding a new code contributor:

  • how long does it take a new code contributor to find the interesting code in this repo?
  • can a reasonably experience Python programmer with no prior optical engineering knowledge make sense of the code?
  • can a new code contributor quickly build all code on a brand-new laptop?
  • are tests sufficient that a new code contributor can make changes without worrying about non-local consequences?
  • is documentation sufficient that a party wishing to integrate this code can understand its APIs and other externally-facing behavior without needing to read through the code?
  • are tests and documentation sufficient that a code contributor can implement new features without needing excessive prior coordination with the core development team?
  • is the development process transparent enough that a code contributor can find roadmaps, tasks, and progres without needing excessive prior coordination with the core development team?

Simplifying Assumptions

The development process introduces a number of variables. These repositories rely on the following simplifying assumptions to reduce the number of variables in our development practice.

We pledge to support development on the following platforms:

  • Linux (specifically, Ubuntu 16.04 LTS or equivalent)
  • OS X (specifically, El Capitan or later)
  • Windows (specifically, Windows 10 or later)

We pledge to support deployment on the following platforms:

  • Linux (specifically, Ubuntu 16.04 LTS or equivalent)

We require the following baseline software dependencies for development and deployment:

  • Python 3.6 (or later)
  • numpy 1.1x (or later)
  • scipy 1.x (or later)

/We may closely track versions of Python, numpy, and scipy. We will maintain a document of potential backwards-incompatibilities./

We support & encourage software dependency management via:

Quick Start

  1. Join the Telecom Infra Project as a member: http://telecominfraproject.com/apply-for-membership/
  2. Join the OOPT mailing list: link needed
  3. Fork this repository & clone locally.
  4. Run pip install -r requirements_dev.txt to install all necessary dependencies.
  5. Run tests to set baseline.
  6. Make code changes.
  7. Run tests & ensure all pass.
  8. Submit pull request via Github.

Code Review & Pull Request Practices

Code contributors will not be allowed to push directly to this repo. Changes to this repo must be made via pull request.

The purpose of our repository is not to reflect the development process. Instead, it is to reflect how the software transitions from working state to working state while managing internal and external dependencies.

Pull requests must satisfy the following conditions:

  • must be rebased into logical commits (i.e., squash commits into those which isolate individual features or changes made, rather than the development process itself. No "typo" commits.)
  • where possible, must transition the repository from working state to working state.
  • if they affect existing functionality, must include amendments to all affected tests.
  • if they introduce new functionality, must include corresponding tests.
  • must include appropriate in-repo documentation.
  • must handle any merge conflicts (i.e., it is the responsibility of the party submitting the pull request to address merge conflicts.)
  • must comport with code quality standards listed below.
  • must comport with branching strategy detailed below.

The following users will have the authority to approve pull requests and tag releases:

The above set of code reviewers has been chosen to provide subject matter expertise in each area involved in gnpy (software development, physical simulation & modelling, and industry optical engineering.) The above set of code reviewers is subject to change.

Pull requests will be accepted via a consensus model, with agreemnet of all reviewing parties above, (understanding that reviewing responsibilities will often be delegated for efficiency.)

Git commit messages will be encouraged to follow the "seven rules of great Git commit messages":

  • Separate subject from body with a blank line
  • Limit the subject line to 50 characters
  • Capitalize the subject line
  • Do not end the subject line with a period
  • Use the imperative mood in the subject line
  • Wrap the body at 72 characters
  • Use the body to explain what and why vs. how

Reference:

Branching (gitflow) & Tagging (semvar)

This repo will follow a simplified gitflow branching model.

To outline:

  • Anything in the master branch must be deployable.
  • To work on a new feature, create a branch with a descriptive name off of master.
  • Commit to that branch locally, pushing your work to a named branch on Github.
  • Open a pull request when ready for merging.
  • After code review and signoff, code will be merged into master.
  • Once merged, "deploy" immediately.

References:

When code in this repo reaches a v1.0 state, we will begin tagging releases. We will tag and version releases in accordance with the semantic versioning model:

To outline:

  • Versions will have three parts: MAJOR.MINOR.PATCH
  • Bumps in MAJOR will indicate backwards-incompatible, usually API-level, changes.
  • Bumps in MINOR will indicate added functionality that may be backwards-compatible.
  • Bumps in PATCH will indicate backwards-compatible bug fixes.

References:

Code Quality: Style Guide

In order to maintain consistent code quality throughout the gnpy codebase, we adopt the following practices:

  • we will rely on Python's PEP-8 as our baseline for code style.
  • we will not mandate specific linting plugins (e.g., flake8) which often introduce busywork.
  • we will not overfocus on style as part of code-review: we will encourage a consistent and standard style but we will not reject code on the sole basis of style (unless in exceptional circumstances.)
  • we will enforce style standards on the basis of locality: code that sits in the same file MUST follow the same code style, code that sides in the same package SHOULD follow the same code style, standalone code is ENCOURAGED to follow a consistent style guide.

We will strongly enforce the following guidelines:

  • spaces must be used for indentation & alignment.
  • code files must be in UTF-8 encoding.
  • lines must be less than 120 characters in length.

We will provide additional guidance on numeric-computing-specific guidelines. For example:

  • we will allow both from numpy import arange and import numpy as np-style imports. (The former is preferred in the case of tight-loops.)

References:

Code Quality: Code Complexity

Our goal is to produce software that can be understood by a sufficiently motivated optical engineer with a reasonable code background.

We will make use of Python, numpy, and other language and library features insofar as they allow us to accomplish our goal. We will allow use of features or mechanisms that would not be immediately understandable to our audience, only with adequate provision of testing and documentation, and only in cases where this complexity is well-circumscribed.

Testing

The intention of testing is to help developers produce robust code within a "tight" iteration cycle.

It is through automated testing that new code contributors can be confident in their work.

We will adopt the following forms of testing:

  • doctests for "explanatory" testing
  • pytest for full-scale "unit" and "integration" testing
  • TODO: custom tests for "validation"

Further guidelines will be available via the code-review process and will be detailed here.

Reference:

Continuous Integration: We will use Travis-CI for continuous integration. Commits that "break the build" will be the responsibility of the author to resolve.

Documentation

We will adopt Sphinx for documentation: http://www.sphinx-doc.org/en/stable/

We will provide three forms of documentation:

  • adhoc text or Sphinx-structured text in function, class, and module docstrings for API-level documentation
  • Sphinx-structured text in a docs/ folder in the repository for supplementary (theoretical, architectural, or non-specific-code-related) documentation
  • pages in the Github wiki (such as this one)

Further guidelines will be available via the code-review process and will be detailed here.

Reference:

General Python Reference

For code contributors new to Python, there are many resources to quickly get up to speed.

For books, we recommend anything by David Beazley, including:

For online tutorials and videos, we recommend checking out https://pyvideo.org, especially any talks from a PyData or SciPy conference.

Below are a sampling of relevant talks that you can find on PyVideo:

Clone this wiki locally