Code workflow

This page presents how we'll collaborate and publish our code. If you're new to Git, please begin by having a look at its core concepts (commits, pull requests, repositories & branches, etc).

Branches

We have 3 types of branches:

• the branch master is our main branch. It's both a production and a continuous development branch: it will be used directly by the production server to power the real website, and new features should be based on this branch.
• the branch staging can be seen as a branch for testing. It powers a test server and if you need to test a new feature in this online environment (e.g. because a local environment is not sufficient), you can merge on this branch to test your feature. Once everything seems good, you can create a PR (pull request) to merge on the branch master!
• the features branches. Each time you want to develop a new feature (e.g. to improve a page layout, add stats for polls, etc.), you want to do it on a new branch based on the master branch. Once you're done and everything works fine on your local environment, just push it and it will trigger the test pipeline. You can then make your PR to merge into master or staging.

As long as the Portail is going under heavy development, we'll not use the staging branch. When you develop a feature, if it works with the fixtures, directly open a PR to merge it into master.

Workflow

You have two choices to work with Git: command line or GUI. If you want to go with a GUI, there are several desktop clients, but PyCharm handles it very well.

Creating a new feature

When starting on a new feature for this app, first checkout and pull prod (branch master) to be up to date. Then create your feature branch named YOUR_NAME/FEATURE_NAME, try to stick to a single YOUR_NAME to easily identify which branches belong to whom. Convention will be all snake_case for branch names.

As an example I would run

git checkout -b florian/my_awesome_feature_number_1

You can work on it, do not hesitate to commit frequently. It's best practice in this first step.

Testing and pushing your branch

You've worked on your branch, the app looks good locally and you want to go further in the process. Have you written unit tests? Have you run tests locally using python manage.py test? More info in the Tests page.

When you're confident with your work, you will want to push your branch. Before doing so, please rebase your branch on master to squash and rewrite commits correctly.

It's very straightforward, when your branch is checked out, just run

git rebase -i master

You will be inside a vim editor with the list of all the commits you've made. You can pick, reword, or fix (squash) any commit to make the commit history looks nicer. Aggregate commits by topic so that it makes sense, remove all the Bugfix try number 2 you may have and so on. The idea is that a PR in the end should contain only a few commits and each commit should represent something.

It's a best practice, but if you're beginning with Git and don't know what this means, don't bother.

All done? Your code still works locally? Then go forward and push your branch.

git push -u origin florian/my_awesome_feature_number_1

or just git push if you already pushed once to this feature branch.

In order to push your feature branch to the Portail-des-eleves repository, you'll need write access! Please ask any of the MinT admins to add you to the team of collaborators (Github team MinT)

Going to prod

Now you're very confident, what you've worked on is amazing so you create a pull request (into branch master) and ping someone to review it, either in the reviewer section on the PR page, or direct message them. Anyone (other than you) can approve the pull request, and one approval is required to merge into prod. To write a good PR, you can take a look at https://www.braintreepayments.com/blog/effective-pull-requests-a-guide/ So please wait enough time for anyone else interested in your work to give you feedback. This part means that you can approve someone PR and you need to be cautious when doing so.

Getting feedback on a PR doesn't mean your code is bad, but all code that is written is always perfectible. Moreover, not everything is written in this wiki, so if you miss a piece of information it's likely that you'll have it in a review if nobody told you about it before. So do not take feedback as a negative thing, but rather an occasion to improve and write more idiomatic code.

Once your PR is reviewed and approved, any member of the team MinT-admins can merge your branch to prod. This will also trigger a pipeline, if all the tests are successful they will have the ability to deploy the latest version to the production server (not done yet). This will be a one click and you will see directly your changes on the real website.

Also, don't forget to delete your branch once it's done!