Conventions

Conventions

• Controllers, which describe API endpoints will be defined under api/views/*. We will be using Flask Blueprints for easier collaborations in view controllers. Be sure to know how to use them.
  ... Blueprints simplify the application by splitting it under relevant components. To register a Blueprint, you must import it and register it under __init__.py.

from api.views import main
app.register_blueprint(main.main)

• The Database Structure will be defined under api/models/*. Look at the Database Schema Section to know how to update your database. We are using SQLAlchemy as our ORM, which allows us to create, query, and filter through the database easily.

For more Flask Conventions, look at this

Code Formatting

Black is an uncompromising Python code formatter, meaning all code formatting nits will be removed from discussion and all of your code will be formatted to one style. Pretty neat, eh. Note that it doesn't change the AST (Abstract Syntax Tree) so it won't optimize/change your code, just the style.

Black makes code review faster by producing the smallest diffs possible. - Black documentation

You may run black before you commit, set up a pre-commit hook, or add it to your code editor and set it to format on save.

Typing

Typing has been added in python 3 under the typing standard module. Static Type checking is also available through mypy, which is also added to flask-boilerplate. Typing allows developers to easily understand code along with removing typing runtime errors you may face when writing python. Mypy is still in production but I'd still encourage you to add types, especially for method arguments and return values.

Logging

Logging is huge. It's the only way to debug changes that happen in production. I've made it such that the logger provides a lot of information including the module it's in, the url that was called, the line number, etc before even showing the message. Flask uses the standard python logging module. Always use logger.exception when logging exceptions. The logs will also be printed in stdout and to the file api.log (unless you change it in app/config.py.

Git Flow

Before you start making changes, make sure you have the most recently updated version of master:

git pull

Make a new branch for your changes:

git checkout -b <branch_name>

If you want to see all of your branches that exist:

git branch

If you want to switch to a branch that already exists:

git checkout <branch_name>

Make sure you commit your changes to your own branch!

Push your code and submit a PR to leave it up for review:

git push

This might walk you through some remote branch push settings, just follow what it says. It should only happen the first time you push to a new branch

Then go to this repo on Github, refresh the page, and you should see an option to create a pull request from your branch.

Squashing Commits

We want to keep the commit log clean with each commit specifying a modification. This is so we can clearly document the changes done and the reasons for doing so. To squash your commits:

$ git rebase -i <the commit hash of the commit before the commit you want to squash to>

This will then open an editor. Remove pick from the commits you want to squash and replace it with a s or squash and save the file. Another editor will open and you can then modify your commit message.

Code Reviews

It is recommended to:

1. Keep PRs small and manageable
2. Put up a PR early on (even before it is ready for review), so you can get early feedback

Labels:

In Progress

Use this while you are working on your changes. Reviewers can take a look to make sure you're on the right track and make some suggestions along the way. Also use this as a way to ask questions about your code (Is this the right way to do x?, Does this follow conventions properly?, etc.).

Ready For Review

Use this when you feel like your code is ready to be thoroughly reviewed before shipping. Assign your PR to your technical lead and teammates who know more about the areas you worked on (Github might have suggestions based on previous contributions).

In Review

Reviewers, set this to indicate the PR is currently being reviewed.

SHIP IT

Reviewers, set this to indicate the PR is ready to be merged, but let the pull requester do the merging.

PRs can't be merged without at least one reviewer approving your changes. If waiting on your reviewer becomes a blocker, bug them about it!