From 62d7bdb72137fbf86b4229180d59702fa10dbe86 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sat, 5 Sep 2020 13:12:21 +0200 Subject: [PATCH] Document the update process Co-authored-by: Jairo Llopis --- docs/updating.md | 66 +++++++++++++++++++++ mkdocs.yml | 10 +++- poetry.lock | 147 +++++++++++++++++++++++++++++++++++++++++++++-- pyproject.toml | 4 +- 4 files changed, 220 insertions(+), 7 deletions(-) diff --git a/docs/updating.md b/docs/updating.md index 09e5c5b90..e42ad7039 100644 --- a/docs/updating.md +++ b/docs/updating.md @@ -42,3 +42,69 @@ repos: language: fail files: "\\.rej$" ``` + +## How the update works + +To understand how the updating process works, take a look at this diagram: + +```mermaid +graph TD + +%% nodes ---------------------------------------------------------- +template_repo("template repository") +template_current("/tmp/template
(current tag)") +template_latest("/tmp/template
(latest tag)") + +project_regen("/tmp/project
(fresh, current version)") +project_current("current project") +project_half("half migrated
project") +project_updated("updated project") +project_applied("updated project
(diff applied)") +project_full("fully updated
and migrated project") + +update["upate current
project in-place
(prompting)
+ run tasks again"] +compare["compare to get diff"] +apply["apply diff"] + +diff("diff") + +%% edges ---------------------------------------------------------- + template_repo --> |git clone| template_current + template_repo --> |git clone| template_latest + + template_current --> |generate and run tasks| project_regen + project_current --> compare + project_current --> |apply pre-migrations| project_half + project_regen --> compare + project_half --> update + template_latest --> update + update --> project_updated + compare --> diff + diff --> apply + project_updated --> apply + apply --> project_applied + project_applied --> |apply post-migrations| project_full + +%% style ---------------------------------------------------------- +classDef grey fill:#e8e8e8; +class compare,update,apply grey; +``` + +As you can see here, `copier` does several things: + +- it regenerates a fresh project from the current template version +- then it compares both version, to get the diff from "fresh project" to "current + project" +- now it applies pre-migrations to your project, and updates the current project with + the latest template changes (asking confirmation) +- finally, it re-applies the previously obtained diff, and then run the + post-migrations + +!!! important + + The diff obtained by comparing the fresh, regenerated project to your + current project can cancel the modifications applied by the update from the latest + template version. During the process, `copier` will ask you confirmation to overwrite or + skip modifications, but in the end, it is possible that nothing has changed (except for + the version in `.copier-answers.yml` of course). This is not a bug: although it can be + quite surprising, this behavior is correct. diff --git a/mkdocs.yml b/mkdocs.yml index a472278a0..55ec6980b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -36,7 +36,11 @@ markdown_extensions: - admonition - codehilite: guess_lang: false - - pymdownx.superfences + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:mermaid2.fence_mermaid - pymdownx.emoji - pymdownx.magiclink - toc: @@ -44,6 +48,10 @@ markdown_extensions: plugins: - search + - mermaid2: + arguments: + flowchart: + curve: basis - mkdocstrings: watch: - copier diff --git a/poetry.lock b/poetry.lock index cce41e37d..5c03604fd 100644 --- a/poetry.lock +++ b/poetry.lock @@ -38,12 +38,13 @@ description = "Classes Without Boilerplate" name = "attrs" optional = false python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*" -version = "20.1.0" +version = "20.2.0" [package.extras] dev = ["coverage (>=5.0.2)", "hypothesis", "pympler", "pytest (>=4.3.0)", "six", "zope.interface", "sphinx", "sphinx-rtd-theme", "pre-commit"] docs = ["sphinx", "sphinx-rtd-theme", "zope.interface"] tests = ["coverage (>=5.0.2)", "hypothesis", "pympler", "pytest (>=4.3.0)", "six", "zope.interface"] +tests_no_zope = ["coverage (>=5.0.2)", "hypothesis", "pympler", "pytest (>=4.3.0)", "six"] [[package]] category = "dev" @@ -89,6 +90,14 @@ typed-ast = ">=1.4.0" [package.extras] d = ["aiohttp (>=3.3.2)", "aiohttp-cors"] +[[package]] +category = "main" +description = "Python package for providing Mozilla's CA Bundle." +name = "certifi" +optional = false +python-versions = "*" +version = "2020.6.20" + [[package]] category = "dev" description = "Validate configuration and produce human readable error messages." @@ -97,6 +106,14 @@ optional = false python-versions = ">=3.6" version = "3.0.0" +[[package]] +category = "main" +description = "Universal encoding detector for Python 2 and 3" +name = "chardet" +optional = false +python-versions = "*" +version = "3.0.4" + [[package]] category = "main" description = "Composable command line interface toolkit" @@ -150,6 +167,14 @@ optional = false python-versions = "*" version = "0.3.1" +[[package]] +category = "main" +description = "EditorConfig File Locator and Interpreter for Python" +name = "editorconfig" +optional = false +python-versions = "*" +version = "0.12.2" + [[package]] category = "dev" description = "execnet: rapid multi-Python deployment" @@ -258,6 +283,14 @@ version = "1.4.30" [package.extras] license = ["editdistance"] +[[package]] +category = "main" +description = "Internationalized Domain Names in Applications (IDNA)" +name = "idna" +optional = false +python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*" +version = "2.10" + [[package]] category = "main" description = "Read metadata from Python packages" @@ -408,6 +441,18 @@ optional = false python-versions = ">=3.6" version = "0.16.0" +[[package]] +category = "main" +description = "JavaScript unobfuscator and beautifier." +name = "jsbeautifier" +optional = false +python-versions = "*" +version = "1.13.0" + +[package.dependencies] +editorconfig = ">=0.12.2" +six = ">=1.13.0" + [[package]] category = "main" description = "Python LiveReload is an awesome tool for web developers" @@ -521,6 +566,25 @@ version = "1.0" [package.dependencies] mkdocs-material = ">=5.0.0" +[[package]] +category = "main" +description = "A MkDocs plugin for including mermaid graphs in markdown sources" +name = "mkdocs-mermaid2-plugin" +optional = false +python-versions = ">=3.5" +version = "0.4.2" + +[package.dependencies] +beautifulsoup4 = ">=4.6.3" +jsbeautifier = "*" +mkdocs = ">=1.0.4" +mkdocs-material = "*" +pymdown-extensions = ">=8.0" +pyyaml = "*" +requests = "*" +setuptools = ">=18.5" +termcolor = "*" + [[package]] category = "main" description = "Automatic documentation from sources, for MkDocs." @@ -930,6 +994,24 @@ optional = false python-versions = "*" version = "2020.7.14" +[[package]] +category = "main" +description = "Python HTTP for Humans." +name = "requests" +optional = false +python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*" +version = "2.24.0" + +[package.dependencies] +certifi = ">=2017.4.17" +chardet = ">=3.0.2,<4" +idna = ">=2.5,<3" +urllib3 = ">=1.21.1,<1.25.0 || >1.25.0,<1.25.1 || >1.25.1,<1.26" + +[package.extras] +security = ["pyOpenSSL (>=0.14)", "cryptography (>=1.3.4)"] +socks = ["PySocks (>=1.5.6,<1.5.7 || >1.5.7)", "win-inet-pton"] + [[package]] category = "main" description = "Python 2 and 3 compatibility utilities" @@ -946,6 +1028,14 @@ optional = false python-versions = "*" version = "1.9.6" +[[package]] +category = "main" +description = "ANSII Color formatting for output in terminal." +name = "termcolor" +optional = false +python-versions = "*" +version = "1.1.0" + [[package]] category = "dev" description = "Python Library for Tom's Obvious, Minimal Language" @@ -1015,6 +1105,19 @@ optional = false python-versions = "*" version = "3.7.4.3" +[[package]] +category = "main" +description = "HTTP library with thread-safe connection pooling, file post, and more." +name = "urllib3" +optional = false +python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, <4" +version = "1.25.10" + +[package.extras] +brotli = ["brotlipy (>=0.6.0)"] +secure = ["certifi", "cryptography (>=1.3.4)", "idna (>=2.0.0)", "pyOpenSSL (>=0.14)", "ipaddress"] +socks = ["PySocks (>=1.5.6,<1.5.7 || >1.5.7,<2.0)"] + [[package]] category = "dev" description = "Virtual Python Environment builder" @@ -1064,10 +1167,10 @@ docs = ["sphinx", "jaraco.packaging (>=3.2)", "rst.linker (>=1.9)"] testing = ["jaraco.itertools", "func-timeout"] [extras] -docs = ["mkdocstrings", "mkdocs-material"] +docs = ["mkdocstrings", "mkdocs-material", "mkdocs-mermaid2-plugin"] [metadata] -content-hash = "b3b931a58efc19984768288946c6f174244664303d587528b4e88ba9d3ce6d3f" +content-hash = "4e57b20658a1e5e81a5332023aaf07188f193a53b8658233ced0d56c7dd40571" lock-version = "1.0" python-versions = "^3.6" @@ -1089,8 +1192,8 @@ atomicwrites = [ {file = "atomicwrites-1.4.0.tar.gz", hash = "sha256:ae70396ad1a434f9c7046fd2dd196fc04b12f9e91ffb859164193be8b6168a7a"}, ] attrs = [ - {file = "attrs-20.1.0-py2.py3-none-any.whl", hash = "sha256:2867b7b9f8326499ab5b0e2d12801fa5c98842d2cbd22b35112ae04bf85b4dff"}, - {file = "attrs-20.1.0.tar.gz", hash = "sha256:0ef97238856430dcf9228e07f316aefc17e8939fc8507e18c6501b761ef1a42a"}, + {file = "attrs-20.2.0-py2.py3-none-any.whl", hash = "sha256:fce7fc47dfc976152e82d53ff92fa0407700c21acd20886a13777a0d20e655dc"}, + {file = "attrs-20.2.0.tar.gz", hash = "sha256:26b54ddbbb9ee1d34d5d3668dd37d6cf74990ab23c828c2888dccdceee395594"}, ] backcall = [ {file = "backcall-0.2.0-py2.py3-none-any.whl", hash = "sha256:fbbce6a29f263178a1f7915c1940bde0ec2b2a967566fe1c65c1dfb7422bd255"}, @@ -1105,10 +1208,18 @@ black = [ {file = "black-19.10b0-py36-none-any.whl", hash = "sha256:1b30e59be925fafc1ee4565e5e08abef6b03fe455102883820fe5ee2e4734e0b"}, {file = "black-19.10b0.tar.gz", hash = "sha256:c2edb73a08e9e0e6f65a0e6af18b059b8b1cdd5bef997d7a0b181df93dc81539"}, ] +certifi = [ + {file = "certifi-2020.6.20-py2.py3-none-any.whl", hash = "sha256:8fc0819f1f30ba15bdb34cceffb9ef04d99f420f68eb75d901e9560b8749fc41"}, + {file = "certifi-2020.6.20.tar.gz", hash = "sha256:5930595817496dd21bb8dc35dad090f1c2cd0adfaf21204bf6732ca5d8ee34d3"}, +] cfgv = [ {file = "cfgv-3.0.0-py2.py3-none-any.whl", hash = "sha256:f22b426ed59cd2ab2b54ff96608d846c33dfb8766a67f0b4a6ce130ce244414f"}, {file = "cfgv-3.0.0.tar.gz", hash = "sha256:04b093b14ddf9fd4d17c53ebfd55582d27b76ed30050193c14e560770c5360eb"}, ] +chardet = [ + {file = "chardet-3.0.4-py2.py3-none-any.whl", hash = "sha256:fc323ffcaeaed0e0a02bf4d117757b98aed530d9ed4531e3e15460124c106691"}, + {file = "chardet-3.0.4.tar.gz", hash = "sha256:84ab92ed1c4d4f16916e05906b6b75a6c0fb5db821cc65e70cbd64a3e2a5eaae"}, +] click = [ {file = "click-7.1.2-py2.py3-none-any.whl", hash = "sha256:dacca89f4bfadd5de3d7489b7c8a566eee0d3676333fbb50030263894c38c0dc"}, {file = "click-7.1.2.tar.gz", hash = "sha256:d2b5255c7c6349bc1bd1e59e08cd12acbbd63ce649f2588755783aa94dfb6b1a"}, @@ -1165,6 +1276,10 @@ distlib = [ {file = "distlib-0.3.1-py2.py3-none-any.whl", hash = "sha256:8c09de2c67b3e7deef7184574fc060ab8a793e7adbb183d942c389c8b13c52fb"}, {file = "distlib-0.3.1.zip", hash = "sha256:edf6116872c863e1aa9d5bb7cb5e05a022c519a4594dc703843343a9ddd9bff1"}, ] +editorconfig = [ + {file = "EditorConfig-0.12.2-py2-none-any.whl", hash = "sha256:60d6f10b87d2572ac1581cb8c9f018163e2b13a9e49588f9fb6dc8c715a1744c"}, + {file = "EditorConfig-0.12.2.tar.gz", hash = "sha256:1b0ef345f9c3a673e492cfe608ed644b236139f7fceab5c6f513a71bcaf8a56c"}, +] execnet = [ {file = "execnet-1.7.1-py2.py3-none-any.whl", hash = "sha256:d4efd397930c46415f62f8a31388d6be4f27a91d7550eb79bc64a756e0056547"}, {file = "execnet-1.7.1.tar.gz", hash = "sha256:cacb9df31c9680ec5f95553976c4da484d407e85e41c83cb812aa014f0eddc50"}, @@ -1199,6 +1314,10 @@ identify = [ {file = "identify-1.4.30-py2.py3-none-any.whl", hash = "sha256:f9f84a4ff44e29b9cc23c4012c2c8954089860723f80ce63d760393e5f197108"}, {file = "identify-1.4.30.tar.gz", hash = "sha256:e105a62fd3a496c701fd1bc4e24eb695455b5efb97e722816d5bd988c3344311"}, ] +idna = [ + {file = "idna-2.10-py2.py3-none-any.whl", hash = "sha256:b97d804b1e9b523befed77c48dacec60e6dcb0b5391d57af6a65a312a90648c0"}, + {file = "idna-2.10.tar.gz", hash = "sha256:b307872f855b18632ce0c21c5e45be78c0ea7ae4c15c828c20788b26921eb3f6"}, +] importlib-metadata = [ {file = "importlib_metadata-1.7.0-py2.py3-none-any.whl", hash = "sha256:dc15b2969b4ce36305c51eebe62d418ac7791e9a157911d58bfb1f9ccd8e2070"}, {file = "importlib_metadata-1.7.0.tar.gz", hash = "sha256:90bb658cdbbf6d1735b6341ce708fc7024a3e14e99ffdc5783edea9f9b077f83"}, @@ -1258,6 +1377,9 @@ joblib = [ {file = "joblib-0.16.0-py3-none-any.whl", hash = "sha256:d348c5d4ae31496b2aa060d6d9b787864dd204f9480baaa52d18850cb43e9f49"}, {file = "joblib-0.16.0.tar.gz", hash = "sha256:8f52bf24c64b608bf0b2563e0e47d6fcf516abc8cfafe10cfd98ad66d94f92d6"}, ] +jsbeautifier = [ + {file = "jsbeautifier-1.13.0.tar.gz", hash = "sha256:f5565fbcd95f79945e124324815e586ae0d2e43df5af82a4400390e6ea789e8b"}, +] livereload = [ {file = "livereload-2.6.3.tar.gz", hash = "sha256:776f2f865e59fde56490a56bcc6773b6917366bce0c267c60ee8aaf1a0959869"}, ] @@ -1320,6 +1442,10 @@ mkdocs-material-extensions = [ {file = "mkdocs-material-extensions-1.0.tar.gz", hash = "sha256:17d7491e189af75700310b7ec33c6c48a22060b8b445001deca040cb60471cde"}, {file = "mkdocs_material_extensions-1.0-py3-none-any.whl", hash = "sha256:09569c3694b5acc1e8334c9730e52b4bcde65fc9d613cc20e49af131ef1a9ca0"}, ] +mkdocs-mermaid2-plugin = [ + {file = "mkdocs-mermaid2-plugin-0.4.2.tar.gz", hash = "sha256:e5844cdf4a2ce719631c1dc6eb18d1c6a5a42c578d14df9de9cbe2aa59a602d5"}, + {file = "mkdocs_mermaid2_plugin-0.4.2-py3-none-any.whl", hash = "sha256:d8485b352db1f6829bb8e3bf59f1c7c971ede8c48adb139ff1d7fb2eb144b797"}, +] mkdocstrings = [ {file = "mkdocstrings-0.13.1-py3-none-any.whl", hash = "sha256:567a18d76d65026327f5c43c565db8a747bdf2370949aace2c5d4f086cc00678"}, {file = "mkdocstrings-0.13.1.tar.gz", hash = "sha256:25bf673c9e5d194fbdc20ea94d8a4caeed88ab4929f27dcf28f920d36a04f40f"}, @@ -1510,6 +1636,10 @@ regex = [ {file = "regex-2020.7.14-cp38-cp38-win_amd64.whl", hash = "sha256:7a2dd66d2d4df34fa82c9dc85657c5e019b87932019947faece7983f2089a840"}, {file = "regex-2020.7.14.tar.gz", hash = "sha256:3a3af27a8d23143c49a3420efe5b3f8cf1a48c6fc8bc6856b03f638abc1833bb"}, ] +requests = [ + {file = "requests-2.24.0-py2.py3-none-any.whl", hash = "sha256:fe75cc94a9443b9246fc7049224f75604b113c36acb93f87b80ed42c44cbb898"}, + {file = "requests-2.24.0.tar.gz", hash = "sha256:b3559a131db72c33ee969480840fff4bb6dd111de7dd27c8ee1f820f4f00231b"}, +] six = [ {file = "six-1.15.0-py2.py3-none-any.whl", hash = "sha256:8b74bedcbbbaca38ff6d7491d76f2b06b3592611af620f8426e82dddb04a5ced"}, {file = "six-1.15.0.tar.gz", hash = "sha256:30639c035cdb23534cd4aa2dd52c3bf48f06e5f4a941509c8bafd8ce11080259"}, @@ -1518,6 +1648,9 @@ soupsieve = [ {file = "soupsieve-1.9.6-py2.py3-none-any.whl", hash = "sha256:feb1e937fa26a69e08436aad4a9037cd7e1d4c7212909502ba30701247ff8abd"}, {file = "soupsieve-1.9.6.tar.gz", hash = "sha256:7985bacc98c34923a439967c1a602dc4f1e15f923b6fcf02344184f86cc7efaa"}, ] +termcolor = [ + {file = "termcolor-1.1.0.tar.gz", hash = "sha256:1d6d69ce66211143803fbc56652b41d73b4a400a2891d7bf7a1cdf4c02de613b"}, +] toml = [ {file = "toml-0.10.1-py2.py3-none-any.whl", hash = "sha256:bda89d5935c2eac546d648028b9901107a595863cb36bae0c73ac804a9b4ce88"}, {file = "toml-0.10.1.tar.gz", hash = "sha256:926b612be1e5ce0634a2ca03470f95169cf16f939018233a670519cb4ac58b0f"}, @@ -1573,6 +1706,10 @@ typing-extensions = [ {file = "typing_extensions-3.7.4.3-py3-none-any.whl", hash = "sha256:7cb407020f00f7bfc3cb3e7881628838e69d8f3fcab2f64742a5e76b2f841918"}, {file = "typing_extensions-3.7.4.3.tar.gz", hash = "sha256:99d4073b617d30288f569d3f13d2bd7548c3a7e4c8de87db09a9d29bb3a4a60c"}, ] +urllib3 = [ + {file = "urllib3-1.25.10-py2.py3-none-any.whl", hash = "sha256:e7983572181f5e1522d9c98453462384ee92a0be7fac5f1413a1e35c56cc0461"}, + {file = "urllib3-1.25.10.tar.gz", hash = "sha256:91056c15fa70756691db97756772bb1eb9678fa585d9184f24534b100dc60f4a"}, +] virtualenv = [ {file = "virtualenv-20.0.31-py2.py3-none-any.whl", hash = "sha256:e0305af10299a7fb0d69393d8f04cb2965dda9351140d11ac8db4e5e3970451b"}, {file = "virtualenv-20.0.31.tar.gz", hash = "sha256:43add625c53c596d38f971a465553f6318decc39d98512bc100fa1b1e839c8dc"}, diff --git a/pyproject.toml b/pyproject.toml index a0a3cab3f..6c2f905dc 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -39,9 +39,10 @@ pyyaml-include = "^1.2" packaging = "^20.4" mkdocstrings = {version = "^0.13.1", optional = true} mkdocs-material = {version = "^5.5.2", optional = true} +mkdocs-mermaid2-plugin = {version = "^0.4.1", optional = true} [tool.poetry.extras] -docs = ["mkdocstrings", "mkdocs-material"] +docs = ["mkdocstrings", "mkdocs-material", "mkdocs-mermaid2-plugin"] [tool.poetry.dev-dependencies] black = {version = "^19.10b0", allow-prereleases = true} @@ -64,6 +65,7 @@ pytest-timeout = "^1.4.1" # TODO Remove from this section and install with poetry install -E docs when fixed mkdocstrings = "^0.13.1" mkdocs-material = "^5.5.5" +mkdocs-mermaid2-plugin = "^0.4.1" [tool.poe.tasks] clean.script = "devtasks:clean"