Guidelines used in Brief.me private and public projects. This document aims at :
- Improving consistency intra- and inter-projects.
- Taking tangible decisions.
- Having a reference document to refer to.
- Helping new developers working on our projects.
Those guidelines are constantly evolving and are the results of discussions from Brief.me's tech team and outside collaborators.
Decorators should be placed at the method level when it exists and at the class level otherwise.
class DummyView(View):
@method_decorator(login_required)
def dispatch(self, request, *args, **kwargs):
if request.user.is_active:
return HttpResponseForbidden("already active")
return super().dispatch(request, *args, **kwargs)
...
@method_decorator(login_required, name="dispatch")
class ChangePasswordView(FormView):
form_class = ChangePasswordForm
template_name = "account/change_password.html"
When having the choice between a mixin and a decorator
for the same functional need, we should use the decorator
(e.g.: LoginRequiredMixin
mixin and login_required
decorator)
we use the display() decorator to customize how the field is presented:
@admin.display(description="dernière mise à jour")
def last_modified(self, obj):
return obj.extendedflatpage.last_modified
When it comes to signals and handlers, we should adopt the following architecture:
app_name
│
└───signals
│ │ __init__.py
│ │ handlers.py
│
│ __init__.py
│ ...
│ apps.py
│ ...
Signal handlers should live in app_name/signals/handlers.py
:
from django.db.models.signals import pre_save
from django.dispatch import receiver
from myapp.models import MyModel
@receiver(pre_save, sender=MyModel)
def my_handler(sender, **kwargs):
pass
Handlers should be registered in app_name/apps.py
:
from django.apps import AppConfig
class AppNameConfig(AppConfig):
name = 'app_name'
verbose_name = "App names"
def ready(self):
import app_name.signals.handlers #noqa
Make sure that AppNameConfig
is loaded in app_name/__init__.py
:
default_app_config = "app_name.apps.AppNameConfig"
If you need to provide signals for other apps to listen to, you must do it in app_name/signals/__init__.py
:
import django.dispatch
my_signal = django.dispatch.Signal(providing_args=["dummy_arg"])
Another app can listen to the signal by using from app_name.signals import my_signal
When calling an endpoint to the Chargify's API, we should always use the methods within the ChargifyHelper
class.
chargify_python
should only be used within ChargifyHelper
methods.
Code formatting is handled by black. We use the default configuration of 88 characters per line
for open source and shared apps and a value of 99 characters for briefme_cms
brief.eco
, brief.science
and briefme-core
.
You can create a file watcher by going into File->Settings...->Tools->File Watchers
and create a new entry with the following config:
This will trigger black without you noticing it.
The philosophy of this specification is based on conventional commits. We adapted it to fit our business needs and habits.
Here is the list of verbs with their usage that must be used in our projects:
Verbs | Usage |
---|---|
fix | Patch a bug |
feat | Add new feature |
refactor | A code change that neither fixes a bug nor adds a feature |
style | Changes that do not affect the meaning of the code (white-space, formatting, ...) |
docs | Documentation only changes |
chore | Changes to configuration files (CI, Makefile, pytest.ini, black.toml, ...) |
test | Adding missing tests or correcting existing tests |
Examples of usage:
git commit -m "feat(editorial): allow admin user to see draft and pending news #1034"
git commit -m "test(menu): fix test name TestGetStatus::test_with_restricted_access_user #34"
git commit -m "chore: release version 2.63.0"
git commit -m "refactor(api_setup): log an error if a menu is not found" -m "Otherwise, end user might be in a poor state without staff knowing it"
Here are the steps to follow when we want to deploy to master / main
. We should follow this process even for small changes to avoid taking down the production site.
- Push the code to
staging
. - Check that the build and deploy steps completed successfully on the Platform.sh UI. You should see a green check if everything is fine, or an orange warning sign is something unexpected happened.
- Open a private session on the browser of the marketing site.
- Open a logged-in session of the editorial site.
- (If there is at least one new migration) Make a backup of the production database with the command
platform backup
. - Push the code to
master / main
. - Open a private session on the browser of the marketing site.
- Open a logged-in session of the editorial site.