pm-coding-template

(If forking this template repo, please update this readme accordingly)

Documents and Illustrates Coding Standards used at Prediction Machine

As you ramp up on contributing code to Prediction Machine, please review the basics:

Dev Environment

• Mac/Linux preferred. For Windows, use WSL
• do use separate virtual env for each repo
• IDE:
  • For long-term contributors we prefer that you use the PyCharm IDE (if you are already using IntelliJ, IntelliJ with Python plugin may work)
  • VSCode may also be viable if that's your strong preference
• Pair Programming:
  • (beta) We are evaluating Code With Me as a way to pair on code, a surprisingly fruitful technique
• Dependencies:
  • Target python3.8 for compatibility (eg with AWS Lambda)
  • Pin dependency versions in requirements.txt with ~=, eg flake8~=3.8.4
• file names are normally all lowercase
• when file names must have multiple words, use _ not -
• Organize code in namespace and files. tests dir inside the namespace
• Configure and use pre-commit hooks. Copy .pre-commit-config.yaml to the root directory of your repo and follow the installation instructions to run it.

Code Contents

• 🛑 No hardcoded credentials:

  • Do not put passwords, API keys or other credentials in source files or jupyter notebooks. Load them from environment variables. This makes your code less brittle and keeps the credentials secure. Winning! 🙌

• 🛑 No hardcoded paths:

  • Do not hardcode your local paths to data files etc. Again, env variables are your friend

• License:

  • Do put a disclaimer at the top of each file
  • See projectname/example.py for an example
  • You can enter it in PyCharm and then pick it

• Documentation:

  • We expect all code to have Google Style Python Docstrings

• Testing:

  • We expect shipped code to have close to 100% test coverage
  • Use pytest as the default testing library

• Type hints:

  • Use type hints and mypy.
  • See projectname/example.py for an example
  • We recommend the mypy plugin for the IDE

Github: branches, pull requests

• 🛑 No new repos: do not create a new repository on your own -- request one from tchklovski. This keeps us more organized and naming consistent. In your request, specify what the code in this repository will be responsible for doing. Consider what should be a shared repo.

• Code is considered "shipped" (🎉) when it is accepted as a pull request and merged in main.

• To be mergeable, red (failed) checks need to be addressed

• Create a branch with a descriptive name, eg tchklovski/01-document-practices Or even tchklovski/docs/01-document-practices. The IDE uses / in branch name to group changes, which can be helpful

• Push your changes to the branch and then submit a pull request to merge to master. Assign the pull request reviewing duties to the person you are reporting to. You can do this in the IDE or on github.

• Use this PR template, with proper description, whenever you raise a new PR.

• Write a descriptive message summarizing your commit, and even state what you are trying to accomplish/larger task you are working on

• Use GitHub Actions to catch problems for you. Actions should run the test suite, black formatting check, mypy type checking, notebook cleaning check, and fail if any of these fail (so that you can fix the pull request rather than break master)

  Feel free to propose enhancements to github actions, eg adding files ending in .zip or .parquet should cause a pull request to fail. The best proposal is one you are ready to implement yourself.

• Update the status badges:

  • code style - black
  • codecov
  • maintainability - codeclimate
  • PM CI Workflow