Add asciidoctor-bibtex for correct references
This commit is contained in:
parent
3dd773d6d8
commit
964d95a8ab
9
Makefile
9
Makefile
|
|
@ -1,5 +1,5 @@
|
|||
|
||||
.PHONY: help pdf
|
||||
.PHONY: pdf
|
||||
|
||||
help:
|
||||
@echo "Please use \`make <target>' where <target> is one of"
|
||||
|
|
@ -8,10 +8,5 @@ help:
|
|||
clean:
|
||||
rm -rf $(BUILDDIR)/*
|
||||
|
||||
html:
|
||||
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
|
||||
@echo
|
||||
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
|
||||
|
||||
pdf:
|
||||
asciidoctor-pdf -a pdf-themesdir=resources/themes -a pdf-theme=book.yml source/main.adoc -t
|
||||
asciidoctor-pdf -r asciidoctor-bibtex -a pdf-themesdir=resources/themes -a pdf-theme=book.yml source/main.adoc -t
|
||||
|
|
|
|||
|
|
@ -9,8 +9,8 @@ Ce livre peut être compilé avec [AsciiDoctor](https://asciidoctor.org/).
|
|||
|
||||
```bash
|
||||
$ gem install asciidoctor-pdf --pre
|
||||
$ gem install asciidoctor-bibtex
|
||||
$ gem install rouge
|
||||
$ gem install asciidoctor-diagram
|
||||
```
|
||||
|
||||
## Conversion en PDF
|
||||
|
|
@ -21,6 +21,11 @@ asciidoctor -a rouge-style=monokai -a pdf-themesdir=resources/themes -a pdf-them
|
|||
asciidoctor-pdf -a pdf-themesdir=resources/themes -a pdf-theme=gwift main.adoc -t -r asciidoctor-diagram
|
||||
```
|
||||
|
||||
## Image Docker
|
||||
|
||||
L'image Docker utilisée par Drone est [celle-ci](https://github.com/asciidoctor/docker-asciidoctor).
|
||||
Elle convient tout ce qu'il faut pour compiler correctement le document en PDF (asciidoctor-pdf, asciidoctor-bibtex, ...).
|
||||
|
||||
## Erreurs connues
|
||||
|
||||
Si `asciidoctor` n'est pas dans le PATH malgré son installation, on peut le trouver grâce à la commande `gem env`, puis à réutiliser (ou à modifier le fichier `.bash_profile` ou `.profile`).
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 9.5 KiB |
|
|
@ -6,6 +6,7 @@ Cédric Declerfayt <jaguarondi27@gmail.com>; Fred Pauchet <fred@grimbox.be>
|
|||
:sectnums:
|
||||
:chapter-label: Chapitre
|
||||
:preface-title: Préface
|
||||
:bibtex-file: source/references.bib
|
||||
:source-highlighter: rouge
|
||||
:icons: font
|
||||
|
||||
|
|
@ -13,7 +14,7 @@ Nous n'allons pas vous mentir: il existe enormément de tutoriaux très bien ré
|
|||
|
||||
L'idée du texte ci-dessous est de jeter les bases d'un bon développement, en survolant l'ensemble des outils permettant de suivre des lignes directrices reconnues, de maintenir une bonne qualité de code au travers des différentes étapes (du développement au déploiement) et de s'assurer du maintient correct de la base de code, en permettant à n'importe qui de reprendre le développement.
|
||||
|
||||
Ces idées ne s'appliquent pas uniquement à Django et à son cadre de travail, ni même au langage Python.
|
||||
Ces idées ne s'appliquent pas uniquement à Django et à son cadre de travail, ni même au langage Python.
|
||||
Juste que ces deux sujets sont de bons candidats et que le cadre de travail est bien défini et suffisamment flexible.
|
||||
|
||||
Django se présente comme un "link:https://www.djangoproject.com/[Framework Web pour perfectionnistes ayant des deadlines]" et suit https://docs.djangoproject.com/en/dev/misc/design-philosophies/[ces quelques principes]:
|
||||
|
|
@ -24,7 +25,7 @@ Django se présente comme un "link:https://www.djangoproject.com/[Framework Web
|
|||
* Rapidité du développement (après une petite courbe d'apprentissage un peu ardue au début ;-))
|
||||
|
||||
Mis côte à côte, l'application de ces principes permet une meilleure stabilité du projet à moyen et long terme.
|
||||
Comme nous le verrons par la suite, et sans être parfait, Django offre une flexibilité énorme
|
||||
Comme nous le verrons par la suite, et sans être parfait, Django offre une flexibilité énorme
|
||||
qui permet de laisser le maximum d'options ouvertes, mais également d'expérimenter facilement plusieurs pistes simultanément,
|
||||
jusqu'au moment de prendre une vraie décision.
|
||||
Tout pour plaire à n'importe quel directeur IT.
|
||||
|
|
@ -59,3 +60,7 @@ include::part-3-django-concepts/_index.adoc[]
|
|||
include::part-4-go-live/_index.adoc[]
|
||||
|
||||
include::part-9-resources/_index.adoc[]
|
||||
|
||||
== Bibliographie
|
||||
|
||||
bibliography::[]
|
||||
|
|
|
|||
|
|
@ -3,56 +3,51 @@
|
|||
"Make it work, make it right, make it fast"
|
||||
-- Kent Beck
|
||||
|
||||
En fonction de vos connaissances et compétences, la création d’une nouvelle application est uneé tape relativement
|
||||
facile à mettre en place.
|
||||
Le code qui permet de faire tourner cette application peut ne pas être élégant, voire buggé jusqu'à la moëlle,
|
||||
il pourra fonctionner et faire "preuve de concept".
|
||||
En fonction de vos connaissances et compétences, la création d’une nouvelle application est uneé tape relativement
|
||||
facile à mettre en place.
|
||||
Le code qui permet de faire tourner cette application peut ne pas être élégant, voire buggé jusqu'à la moëlle,
|
||||
il pourra fonctionner et faire "preuve de concept".
|
||||
|
||||
Les problèmes arriveront lorsqu'une nouvelle demande sera introduite, lorsqu'un bug sera découvert et devra être corrigé
|
||||
ou lorsqu'une dépendance cessera de fonctionner ou d'être disponible.
|
||||
Or, une application qui n’évolue pas, meurt.
|
||||
Tout application est donc destinée, soit à être modifiée, corrigée et suivie, soit à déperrir et à être délaissée
|
||||
Les problèmes arriveront lorsqu'une nouvelle demande sera introduite, lorsqu'un bug sera découvert et devra être corrigé
|
||||
ou lorsqu'une dépendance cessera de fonctionner ou d'être disponible.
|
||||
Or, une application qui n’évolue pas, meurt.
|
||||
Tout application est donc destinée, soit à être modifiée, corrigée et suivie, soit à déperrir et à être délaissée
|
||||
par ses utilisateurs.
|
||||
Et c’est juste cette maintenance qui est difficile.
|
||||
Et c’est juste cette maintenance qui est difficile.
|
||||
|
||||
L’application des principes présentés et agrégés ci-dessous permet surtout de préparer correctement tout ce qui pourra arriver,
|
||||
sans aller jusqu’au « *YAGNI* » qui consiste à surcharger tout développement avec des fonctionnalités non demandées,
|
||||
juste « au cas ou ». Pour paraphraser une partie de l’introduction:
|
||||
L’application des principes présentés et agrégés ci-dessous permet surtout de préparer correctement tout ce qui pourra arriver,
|
||||
sans aller jusqu’au « *You Ain't Gonna Need It* » (ou *YAGNI*), qui consiste à surcharger tout développement avec des fonctionnalités non demandées, juste « au cas ou ».
|
||||
Pour paraphraser une partie de l’introduction du livre _Clean Architecture_ cite:[clean_architecture]:
|
||||
|
||||
[quote]
|
||||
----
|
||||
Getting software right is hard: it takes knowledge and skills that most young programmers don’t take the time to develop.
|
||||
It requires a level of discipline and dedication that most programmers never dreamed they’d need.
|
||||
[quote, Robert C. Martin, Clean Architecture]
|
||||
Getting software right is hard: it takes knowledge and skills that most young programmers don’t take the time to develop.
|
||||
It requires a level of discipline and dedication that most programmers never dreamed they’d need.
|
||||
Mostly, it takes a passion for the craft and the desire to be a professional.
|
||||
-- Robert C. Martin, Clean Architecture
|
||||
----
|
||||
|
||||
Le développement d'un logiciel nécessite une rigueur d'exécution et des connaissances précises dans des
|
||||
domaines extrêmement variés.
|
||||
Le développement d'un logiciel nécessite une rigueur d'exécution et des connaissances précises dans des
|
||||
domaines extrêmement variés.
|
||||
Il nécessite également des intentions, des (bonnes) décisions et énormément d'attention.
|
||||
Indépendamment de l'architecture que vous aurez choisie, des technologies que vous aurez patiemment évaluées et mises en place,
|
||||
une architecture et une solution peuvent être cassées en un instant, en même temps que tout ce que vous aurez construit,
|
||||
une architecture et une solution peuvent être cassées en un instant, en même temps que tout ce que vous aurez construit,
|
||||
dès que vous en aurez détourné le regard.
|
||||
|
||||
Un des objectifs ici est de placer les barrières et les gardes-fous (ou plutôt, les "*garde-vous*"), afin
|
||||
de péréniser au maximum les acquis, stabiliser les bases de tous les environnements (du développement à la production)
|
||||
qui pourraient accueillir notre application et fiabiliser les étapes de communication.
|
||||
Un des objectifs ici est de placer les barrières et les gardes-fous (ou plutôt, les "*garde-vous*"), afin de péréniser au maximum les acquis, stabiliser les bases de tous les environnements (du développement à la production) qui pourraient accueillir notre application et fiabiliser les étapes de communication.
|
||||
|
||||
[quote]
|
||||
----
|
||||
A software system that is hard to develop is not likely to have a long and healthy lifetime
|
||||
A software system that is hard to develop is not likely to have a long and healthy lifetime
|
||||
-- Robert C. Martin, Clean Architecture, Chapitre 15, What is architecture ?, page 137
|
||||
----
|
||||
|
||||
Dans cette partie, nous allons parler de *méthodes de travail*, avec comme objectif d'éviter que l'application ne tourne que sur notre machine et que chaque déploiement ne soit une plaie à gérer.
|
||||
Dans cette partie, nous allons parler de *méthodes de travail*, avec comme objectif d'éviter que l'application ne tourne que sur notre machine et que chaque déploiement ne soit une plaie à gérer.
|
||||
Chaque mise à jour doit être réalisable de la manière la plus simple possible:
|
||||
|
||||
. démarrer un script,
|
||||
. prévoir un rollback si cela plante (et si cela a planté, préparer un post-mortem de l'incident pour qu'il ne se produise plus)
|
||||
. se préparer une tisane en regardant nos flux RSS (si cette technologie existe encore...).
|
||||
|
||||
NOTE: La plupart des commandes qui seront présentées dans ce livre le seront depuis un shell sous GNU/Linux.
|
||||
Certaines d'entre elles pourraient devoir être adaptées si vous utilisez un autre système d'exploitation (macOS)
|
||||
NOTE: La plupart des commandes qui seront présentées dans ce livre le seront depuis un shell sous GNU/Linux.
|
||||
Certaines d'entre elles pourraient devoir être adaptées si vous utilisez un autre système d'exploitation (macOS)
|
||||
ou n'importe quelle autre grosse bouse commerciale.
|
||||
|
||||
include::maintainable-applications/_index.adoc[]
|
||||
|
|
|
|||
|
|
@ -1,38 +1,33 @@
|
|||
[quote]
|
||||
----
|
||||
[quote, Brian Foote and Joseph Yoder]
|
||||
If you think good architecture is expensive, try bad architecture
|
||||
-- Brian Foote and Joseph Yoder
|
||||
----
|
||||
|
||||
|
||||
[quote]
|
||||
----
|
||||
[quote, Robert C. Martin, Clean Architecture]
|
||||
A computer program is a detailed description of the policy by which inputs are transformed into outputs.
|
||||
-- Robert C. Martin, Clean Architecture
|
||||
----
|
||||
|
||||
Au delà des principes SOLID dont il est question plus haut,
|
||||
c’est à nouveau dans les ressources proposées et les cas démontrés que l’on comprend leur intérêt:
|
||||
plus que de la définition d’une architecture adéquate, c’est surtout dans la facilité de maintenance
|
||||
d’une application que ces principes s’identifient.
|
||||
|
||||
Derrière une bonne architecture, il y a aussi un investissement quant aux ressources qui seront nécessaires
|
||||
à faire évoluer l’application.
|
||||
Au delà des principes SOLID dont il est question plus haut,
|
||||
c’est à nouveau dans les ressources proposées et les cas démontrés que l’on comprend leur intérêt:
|
||||
plus que de la définition d’une architecture adéquate, c’est surtout dans la facilité de maintenance
|
||||
d’une application que ces principes s’identifient.
|
||||
|
||||
Derrière une bonne architecture, il y a aussi un investissement quant aux ressources qui seront nécessaires
|
||||
à faire évoluer l’application.
|
||||
Ne pas investir dès qu’on le peut va juste lentement remplir la case de la dette technique.
|
||||
|
||||
Good architecture makes the system easy to understand, easy to develop, easy to maintain and easy to deploy.
|
||||
Good architecture makes the system easy to understand, easy to develop, easy to maintain and easy to deploy.
|
||||
The ultimate goal is to minimize the lifetime cost of the system and to maximize programmer productivity.
|
||||
-- Robert C. Martin, Clean Architecture, Chapitre 15, what is architecture ?, page 137
|
||||
|
||||
L’objectif d'une bonne architecture est également de garder le plus d’options possibles,
|
||||
de se concentrer sur les détails (le type de base de données, la conception concrète, ...),
|
||||
le plus tard possible, tout en conservant la politique principale en ligne de mire.
|
||||
Cela permet de délayer les choix techniques à « plus tard », ce qui permet également de concrétiser ces choix
|
||||
L’objectif d'une bonne architecture est également de garder le plus d’options possibles,
|
||||
de se concentrer sur les détails (le type de base de données, la conception concrète, ...),
|
||||
le plus tard possible, tout en conservant la politique principale en ligne de mire.
|
||||
Cela permet de délayer les choix techniques à « plus tard », ce qui permet également de concrétiser ces choix
|
||||
en ayant le plus d’informations possibles.
|
||||
-- Robert C. Martin, Clean Architecture, page 141 - What is architecture ?
|
||||
|
||||
Une architecture ouverte et pouvant être étendue n’a d’intérêt que si le
|
||||
développement est suivi et que les gestionnaires (et architectes) s’engagent à économiser du temps
|
||||
Une architecture ouverte et pouvant être étendue n’a d’intérêt que si le
|
||||
développement est suivi et que les gestionnaires (et architectes) s’engagent à économiser du temps
|
||||
et de la qualité lorsque des changements seront demandés pour l’évolution du projet.
|
||||
|
||||
==== Politiques et règles métiers
|
||||
|
|
@ -42,56 +37,53 @@ TODO: Un p'tit bout à ajouter sur les méthodes de conception ;)
|
|||
|
||||
==== Considération sur les frameworks
|
||||
|
||||
[quote]
|
||||
----
|
||||
[quote, Robert C. Martin, Clean Architecture, p. 199]
|
||||
Frameworks are tools to be used, not architectures to be conformed to.
|
||||
Your architecture should tell readers about the system, not about the frameworks you used in your system.
|
||||
If you are building a health care system, then when new programmers look at the source repository,
|
||||
their first impression should be, « oh, this is a health care system ».
|
||||
Those new programmers should be able to learn all the use cases of the system,
|
||||
Your architecture should tell readers about the system, not about the frameworks you used in your system.
|
||||
If you are building a health care system, then when new programmers look at the source repository,
|
||||
their first impression should be, « oh, this is a health care system ».
|
||||
Those new programmers should be able to learn all the use cases of the system,
|
||||
yet still not know how the system is delivered.
|
||||
-- Robert C. Martin, Clean Architecture, page 199
|
||||
----
|
||||
|
||||
Le point soulevé ci-dessous est qu'un framework n'est qu'un outil, et pas une obligation de structuration.
|
||||
L'idée est que le framework doit se conformer à la définition de l'application, et non l'inverse.
|
||||
Dans le cadre de l'utilisation de Django, c'est un point critique à prendre en considération: une fois que vous aurez fait
|
||||
L'idée est que le framework doit se conformer à la définition de l'application, et non l'inverse.
|
||||
Dans le cadre de l'utilisation de Django, c'est un point critique à prendre en considération: une fois que vous aurez fait
|
||||
ce choix, vous aurez extrêmement difficile à faire machine arrière:
|
||||
|
||||
- Votre modèle métier sera largement couplé avec le type de base de données (relationnelle, indépendamment
|
||||
- Votre modèle métier sera largement couplé avec le type de base de données (relationnelle, indépendamment
|
||||
- Votre couche de présentation sera surtout disponible au travers d'un navigateur
|
||||
- Les droits d'accès et permissions seront en grosse partie gérés par le frameworks
|
||||
- La sécurité dépendra de votre habilité à suivre les versions
|
||||
- Et les fonctionnalités complémentaires (que vous n'aurez pas voulu/eu le temps de développer) dépendront
|
||||
- La sécurité dépendra de votre habilité à suivre les versions
|
||||
- Et les fonctionnalités complémentaires (que vous n'aurez pas voulu/eu le temps de développer) dépendront
|
||||
de la bonne volonté de la communauté
|
||||
|
||||
Le point à comprendre ici n'est pas que "Django, c'est mal", mais qu'une fois que vous aurez défini la politique,
|
||||
Le point à comprendre ici n'est pas que "Django, c'est mal", mais qu'une fois que vous aurez défini la politique,
|
||||
les règles métiers, les données critiques et entités, et que vous aurez fait le choix de développer en âme et conscience
|
||||
votre nouvelle création en utilisant Django, vous serez bon gré mal gré, contraint de continuer avec.
|
||||
Cette décision ne sera pas irrévocable, mais difficile à contourner.
|
||||
Cette décision ne sera pas irrévocable, mais difficile à contourner.
|
||||
|
||||
> At some point in their history most DevOps organizations were hobbled by tightly-coupled, monolithic architectures that while extremely successfull at helping them achieve product/market fit - put them at risk of organizational failure once they had to operate at scale (e.g. eBay's monolithic C++ application in 2001, Amazon's monolithic OBIDOS application in 2001, Twitter's monolithic Rails front-end in 2009, and LinkedIn's monolithic Leo application in 2011).
|
||||
> At some point in their history most DevOps organizations were hobbled by tightly-coupled, monolithic architectures that while extremely successfull at helping them achieve product/market fit - put them at risk of organizational failure once they had to operate at scale (e.g. eBay's monolithic C++ application in 2001, Amazon's monolithic OBIDOS application in 2001, Twitter's monolithic Rails front-end in 2009, and LinkedIn's monolithic Leo application in 2011).
|
||||
> In each of these cases, they were able to re-architect their systems and set the stage not only to survice, but also to thrise and win in the marketplace
|
||||
> The DevOps Handbook, Part III - The Principles of Flow - Architect for low-risk release (page 182)
|
||||
|
||||
Ceci dit, Django compense ses contraintes en proposant énormément de flexibilité et de fonctionnalités
|
||||
Ceci dit, Django compense ses contraintes en proposant énormément de flexibilité et de fonctionnalités
|
||||
*out-of-the-box*, c'est-à-dire que vous pourrez sans doute avancer vite et bien jusqu'à un point de rupture,
|
||||
puis revoir la conception et réinvestir à ce moment-là, mais en toute connaissance de cause.
|
||||
puis revoir la conception et réinvestir à ce moment-là, mais en toute connaissance de cause.
|
||||
|
||||
[quote]
|
||||
----
|
||||
When any of the external parts of the system become obsolete, such as the database, or the web framework,
|
||||
When any of the external parts of the system become obsolete, such as the database, or the web framework,
|
||||
you can replace those obsolete elements with a minimum of fuss.
|
||||
-- Robert C. Martin, Clean Architecture, page 209
|
||||
----
|
||||
|
||||
Avec Django, la difficulté à se passer du framework va consister à basculer vers « autre chose » et a remplacer
|
||||
chacune des tentacules qui aura pousser partout dans l’application.
|
||||
Avec Django, la difficulté à se passer du framework va consister à basculer vers « autre chose » et a remplacer
|
||||
chacune des tentacules qui aura pousser partout dans l’application.
|
||||
|
||||
NOTE: A noter que les services et les « architectures orientées services » ne sont jamais qu’une définition
|
||||
d’implémentation des frontières, dans la mesure où un service n’est jamais qu’une fonction appelée au travers d'un protocole
|
||||
NOTE: A noter que les services et les « architectures orientées services » ne sont jamais qu’une définition
|
||||
d’implémentation des frontières, dans la mesure où un service n’est jamais qu’une fonction appelée au travers d'un protocole
|
||||
(rest, soap, ...).
|
||||
Une application monolotihique est tout aussi fonctionnelle qu’une application découpée en microservices.
|
||||
Une application monolotihique est tout aussi fonctionnelle qu’une application découpée en microservices.
|
||||
(Services: great and small, page 243).
|
||||
|
||||
==== Un point sur l'inversion de dépendances
|
||||
|
|
@ -99,10 +91,10 @@ Une application monolotihique est tout aussi fonctionnelle qu’une application
|
|||
Dans la partie SOLID, nous avons évoqué plusieurs principes de développement.
|
||||
Django est un framework qui évolue, et qui a pu présenter certains problèmes liés à l'un de ces principes.
|
||||
|
||||
Les [https://docs.djangoproject.com/en/2.0/releases/2.0/](release notes) de Django 2.0 date de décembre 2017; parmi ces notes,
|
||||
Les [https://docs.djangoproject.com/en/2.0/releases/2.0/](release notes) de Django 2.0 date de décembre 2017; parmi ces notes,
|
||||
l'une d'elles cite l'abandon du support d'[https://docs.djangoproject.com/en/2.0/releases/2.0/#dropped-support-for-oracle-11-2](Oracle 11.2).
|
||||
En substance, cela signifie que le framework se chargeait lui-même de construire certaines parties de requêtes,
|
||||
qui deviennent non fonctionnelles dès lors que l'on met le framework ou le moteur de base de données à jour.
|
||||
En substance, cela signifie que le framework se chargeait lui-même de construire certaines parties de requêtes,
|
||||
qui deviennent non fonctionnelles dès lors que l'on met le framework ou le moteur de base de données à jour.
|
||||
Réécrit, cela signifie que:
|
||||
|
||||
1. Si vos données sont stockées dans un moteur géré par Oracle 11.2, vous serez limité à une version 1.11 de Django
|
||||
|
|
@ -113,7 +105,7 @@ ne devraient pas avoir connaissance du moteur de base de données.
|
|||
Pire, vos politiques et données métiers ne devraient pas avoir connaissance **de la version** du moteur de base de données.
|
||||
|
||||
En conclusion, le choix d'une version d'un moteur technique (*la base de données*) a une incidence directe sur les fonctionnalités
|
||||
mises à disposition par votre application, ce qui va à l'encontre des 12 facteurs (et des principes de développement).
|
||||
mises à disposition par votre application, ce qui va à l'encontre des 12 facteurs (et des principes de développement).
|
||||
|
||||
Ce point sera rediscuté par la suite, notamment au niveau de l'épinglage des versions, de la reproduction des environnements
|
||||
et de l'interdépendance entre des choix techniques et fonctionnels.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,9 @@
|
|||
@book{clean_architecture,
|
||||
title = {Clean Architecture, A Craftman's Guide to Software Structure and Design},
|
||||
author = {Robert C. Martin},
|
||||
publisher = {Pearson},
|
||||
editor = {Addison-Wesley},
|
||||
isbn = {978-0-13-449416-6},
|
||||
year = {2018},
|
||||
type = {Book}
|
||||
}
|
||||
Loading…
Reference in New Issue