diff --git a/documentation/Pipfile b/documentation/Pipfile index ae584424536..7f4c6fe97e2 100644 --- a/documentation/Pipfile +++ b/documentation/Pipfile @@ -4,12 +4,14 @@ verify_ssl = true name = "pypi" [packages] +sphinxcontrib-mermaid = "*" [dev-packages] sphinx = "*" sphinx-autobuild = "*" furo = "*" myst-parser = "*" +sphinxcontrib-mermaid = "*" [requires] python_version = "3.10" diff --git a/documentation/Pipfile.lock b/documentation/Pipfile.lock index 1040a77ad54..8cb0f2af66e 100644 --- a/documentation/Pipfile.lock +++ b/documentation/Pipfile.lock @@ -1,7 +1,7 @@ { "_meta": { "hash": { - "sha256": "08f2f2ccaf2dc674900f40a9d58969523460d490e3f20ea95598e4e9cfce86e7" + "sha256": "3f5f4c537fce3734eaae2570f6aaa43fe974d79624e708232e21163b34ac9f64" }, "pipfile-spec": 6, "requires": { @@ -15,132 +15,129 @@ } ] }, - "default": {}, + "default": { + "sphinxcontrib-mermaid": { + "hashes": [ + "sha256:15491c24ec78cf1626b1e79e797a9ce87cb7959cf38f955eb72dd5512aeb6ce9", + "sha256:fa3e5325d4ba395336e6137d113f55026b1a03ccd115dc54113d1d871a580466" + ], + "index": "pypi", + "version": "==0.8.1" + } + }, "develop": { "alabaster": { "hashes": [ "sha256:1ee19aca801bbabb5ba3f5f258e4422dfa86f82f3e9cefb0859b283cdd7f62a3", "sha256:a27a4a084d5e690e16e01e03ad2b2e552c61a65469419b907243193de1a84ae2" ], - "markers": "python_full_version >= '3.6.0'", + "markers": "python_version >= '3.6'", "version": "==0.7.13" }, "babel": { "hashes": [ - "sha256:468e6cd1e2b571a1663110fc737e3a7d9069d038e0c9c4a7f158caeeafe4089c", - "sha256:8f8b752c803e9f9e03ff219b644aceb0dbcf081c55a88ea11f86291e60a7bb68" + "sha256:b4246fb7677d3b98f501a39d43396d3cafdc8eadb045f4a31be01863f655c610", + "sha256:cc2d99999cd01d44420ae725a21c9e3711b3aadc7976d6147f622d8581963455" ], "markers": "python_version >= '3.7'", - "version": "==2.12.0" + "version": "==2.12.1" }, "beautifulsoup4": { "hashes": [ - "sha256:0e79446b10b3ecb499c1556f7e228a53e64a2bfcebd455f370d8927cb5b59e39", - "sha256:bc4bdda6717de5a2987436fb8d72f45dc90dd856bdfd512a1314ce90349a0106" + "sha256:2130a5ad7f513200fae61a17abb5e338ca980fa28c439c0571014bc0217e9591", + "sha256:c5fceeaec29d09c84970e47c65f2f0efe57872f7cff494c9691a26ec0ff13234" ], - "markers": "python_full_version >= '3.6.0'", - "version": "==4.11.2" + "markers": "python_version >= '3.6'", + "version": "==4.12.0" }, "certifi": { "hashes": [ "sha256:35824b4c3a97115964b408844d64aa14db1cc518f6562e8d7261699d1350a9e3", "sha256:4ad3232f5e926d6718ec31cfc1fcadfde020920e278684144551c91769c7bc18" ], - "markers": "python_full_version >= '3.6.0'", + "markers": "python_version >= '3.6'", "version": "==2022.12.7" }, "charset-normalizer": { "hashes": [ - "sha256:00d3ffdaafe92a5dc603cb9bd5111aaa36dfa187c8285c543be562e61b755f6b", - "sha256:024e606be3ed92216e2b6952ed859d86b4cfa52cd5bc5f050e7dc28f9b43ec42", - "sha256:0298eafff88c99982a4cf66ba2efa1128e4ddaca0b05eec4c456bbc7db691d8d", - "sha256:02a51034802cbf38db3f89c66fb5d2ec57e6fe7ef2f4a44d070a593c3688667b", - "sha256:083c8d17153ecb403e5e1eb76a7ef4babfc2c48d58899c98fcaa04833e7a2f9a", - "sha256:0a11e971ed097d24c534c037d298ad32c6ce81a45736d31e0ff0ad37ab437d59", - "sha256:0bf2dae5291758b6f84cf923bfaa285632816007db0330002fa1de38bfcb7154", - "sha256:0c0a590235ccd933d9892c627dec5bc7511ce6ad6c1011fdf5b11363022746c1", - "sha256:0f438ae3532723fb6ead77e7c604be7c8374094ef4ee2c5e03a3a17f1fca256c", - "sha256:109487860ef6a328f3eec66f2bf78b0b72400280d8f8ea05f69c51644ba6521a", - "sha256:11b53acf2411c3b09e6af37e4b9005cba376c872503c8f28218c7243582df45d", - "sha256:12db3b2c533c23ab812c2b25934f60383361f8a376ae272665f8e48b88e8e1c6", - "sha256:14e76c0f23218b8f46c4d87018ca2e441535aed3632ca134b10239dfb6dadd6b", - "sha256:16a8663d6e281208d78806dbe14ee9903715361cf81f6d4309944e4d1e59ac5b", - "sha256:292d5e8ba896bbfd6334b096e34bffb56161c81408d6d036a7dfa6929cff8783", - "sha256:2c03cc56021a4bd59be889c2b9257dae13bf55041a3372d3295416f86b295fb5", - "sha256:2e396d70bc4ef5325b72b593a72c8979999aa52fb8bcf03f701c1b03e1166918", - "sha256:2edb64ee7bf1ed524a1da60cdcd2e1f6e2b4f66ef7c077680739f1641f62f555", - "sha256:31a9ddf4718d10ae04d9b18801bd776693487cbb57d74cc3458a7673f6f34639", - "sha256:356541bf4381fa35856dafa6a965916e54bed415ad8a24ee6de6e37deccf2786", - "sha256:358a7c4cb8ba9b46c453b1dd8d9e431452d5249072e4f56cfda3149f6ab1405e", - "sha256:37f8febc8ec50c14f3ec9637505f28e58d4f66752207ea177c1d67df25da5aed", - "sha256:39049da0ffb96c8cbb65cbf5c5f3ca3168990adf3551bd1dee10c48fce8ae820", - "sha256:39cf9ed17fe3b1bc81f33c9ceb6ce67683ee7526e65fde1447c772afc54a1bb8", - "sha256:3ae1de54a77dc0d6d5fcf623290af4266412a7c4be0b1ff7444394f03f5c54e3", - "sha256:3b590df687e3c5ee0deef9fc8c547d81986d9a1b56073d82de008744452d6541", - "sha256:3e45867f1f2ab0711d60c6c71746ac53537f1684baa699f4f668d4c6f6ce8e14", - "sha256:3fc1c4a2ffd64890aebdb3f97e1278b0cc72579a08ca4de8cd2c04799a3a22be", - "sha256:4457ea6774b5611f4bed5eaa5df55f70abde42364d498c5134b7ef4c6958e20e", - "sha256:44ba614de5361b3e5278e1241fda3dc1838deed864b50a10d7ce92983797fa76", - "sha256:4a8fcf28c05c1f6d7e177a9a46a1c52798bfe2ad80681d275b10dcf317deaf0b", - "sha256:4b0d02d7102dd0f997580b51edc4cebcf2ab6397a7edf89f1c73b586c614272c", - "sha256:502218f52498a36d6bf5ea77081844017bf7982cdbe521ad85e64cabee1b608b", - "sha256:503e65837c71b875ecdd733877d852adbc465bd82c768a067badd953bf1bc5a3", - "sha256:5995f0164fa7df59db4746112fec3f49c461dd6b31b841873443bdb077c13cfc", - "sha256:59e5686dd847347e55dffcc191a96622f016bc0ad89105e24c14e0d6305acbc6", - "sha256:601f36512f9e28f029d9481bdaf8e89e5148ac5d89cffd3b05cd533eeb423b59", - "sha256:608862a7bf6957f2333fc54ab4399e405baad0163dc9f8d99cb236816db169d4", - "sha256:62595ab75873d50d57323a91dd03e6966eb79c41fa834b7a1661ed043b2d404d", - "sha256:70990b9c51340e4044cfc394a81f614f3f90d41397104d226f21e66de668730d", - "sha256:71140351489970dfe5e60fc621ada3e0f41104a5eddaca47a7acb3c1b851d6d3", - "sha256:72966d1b297c741541ca8cf1223ff262a6febe52481af742036a0b296e35fa5a", - "sha256:74292fc76c905c0ef095fe11e188a32ebd03bc38f3f3e9bcb85e4e6db177b7ea", - "sha256:761e8904c07ad053d285670f36dd94e1b6ab7f16ce62b9805c475b7aa1cffde6", - "sha256:772b87914ff1152b92a197ef4ea40efe27a378606c39446ded52c8f80f79702e", - "sha256:79909e27e8e4fcc9db4addea88aa63f6423ebb171db091fb4373e3312cb6d603", - "sha256:7e189e2e1d3ed2f4aebabd2d5b0f931e883676e51c7624826e0a4e5fe8a0bf24", - "sha256:7eb33a30d75562222b64f569c642ff3dc6689e09adda43a082208397f016c39a", - "sha256:81d6741ab457d14fdedc215516665050f3822d3e56508921cc7239f8c8e66a58", - "sha256:8499ca8f4502af841f68135133d8258f7b32a53a1d594aa98cc52013fff55678", - "sha256:84c3990934bae40ea69a82034912ffe5a62c60bbf6ec5bc9691419641d7d5c9a", - "sha256:87701167f2a5c930b403e9756fab1d31d4d4da52856143b609e30a1ce7160f3c", - "sha256:88600c72ef7587fe1708fd242b385b6ed4b8904976d5da0893e31df8b3480cb6", - "sha256:8ac7b6a045b814cf0c47f3623d21ebd88b3e8cf216a14790b455ea7ff0135d18", - "sha256:8b8af03d2e37866d023ad0ddea594edefc31e827fee64f8de5611a1dbc373174", - "sha256:8c7fe7afa480e3e82eed58e0ca89f751cd14d767638e2550c77a92a9e749c317", - "sha256:8eade758719add78ec36dc13201483f8e9b5d940329285edcd5f70c0a9edbd7f", - "sha256:911d8a40b2bef5b8bbae2e36a0b103f142ac53557ab421dc16ac4aafee6f53dc", - "sha256:93ad6d87ac18e2a90b0fe89df7c65263b9a99a0eb98f0a3d2e079f12a0735837", - "sha256:95dea361dd73757c6f1c0a1480ac499952c16ac83f7f5f4f84f0658a01b8ef41", - "sha256:9ab77acb98eba3fd2a85cd160851816bfce6871d944d885febf012713f06659c", - "sha256:9cb3032517f1627cc012dbc80a8ec976ae76d93ea2b5feaa9d2a5b8882597579", - "sha256:9cf4e8ad252f7c38dd1f676b46514f92dc0ebeb0db5552f5f403509705e24753", - "sha256:9d9153257a3f70d5f69edf2325357251ed20f772b12e593f3b3377b5f78e7ef8", - "sha256:a152f5f33d64a6be73f1d30c9cc82dfc73cec6477ec268e7c6e4c7d23c2d2291", - "sha256:a16418ecf1329f71df119e8a65f3aa68004a3f9383821edcb20f0702934d8087", - "sha256:a60332922359f920193b1d4826953c507a877b523b2395ad7bc716ddd386d866", - "sha256:a8d0fc946c784ff7f7c3742310cc8a57c5c6dc31631269876a88b809dbeff3d3", - "sha256:ab5de034a886f616a5668aa5d098af2b5385ed70142090e2a31bcbd0af0fdb3d", - "sha256:c22d3fe05ce11d3671297dc8973267daa0f938b93ec716e12e0f6dee81591dc1", - "sha256:c2ac1b08635a8cd4e0cbeaf6f5e922085908d48eb05d44c5ae9eabab148512ca", - "sha256:c512accbd6ff0270939b9ac214b84fb5ada5f0409c44298361b2f5e13f9aed9e", - "sha256:c75ffc45f25324e68ab238cb4b5c0a38cd1c3d7f1fb1f72b5541de469e2247db", - "sha256:c95a03c79bbe30eec3ec2b7f076074f4281526724c8685a42872974ef4d36b72", - "sha256:cadaeaba78750d58d3cc6ac4d1fd867da6fc73c88156b7a3212a3cd4819d679d", - "sha256:cd6056167405314a4dc3c173943f11249fa0f1b204f8b51ed4bde1a9cd1834dc", - "sha256:db72b07027db150f468fbada4d85b3b2729a3db39178abf5c543b784c1254539", - "sha256:df2c707231459e8a4028eabcd3cfc827befd635b3ef72eada84ab13b52e1574d", - "sha256:e62164b50f84e20601c1ff8eb55620d2ad25fb81b59e3cd776a1902527a788af", - "sha256:e696f0dd336161fca9adbb846875d40752e6eba585843c768935ba5c9960722b", - "sha256:eaa379fcd227ca235d04152ca6704c7cb55564116f8bc52545ff357628e10602", - "sha256:ebea339af930f8ca5d7a699b921106c6e29c617fe9606fa7baa043c1cdae326f", - "sha256:f4c39b0e3eac288fedc2b43055cfc2ca7a60362d0e5e87a637beac5d801ef478", - "sha256:f5057856d21e7586765171eac8b9fc3f7d44ef39425f85dbcccb13b3ebea806c", - "sha256:f6f45710b4459401609ebebdbcfb34515da4fc2aa886f95107f556ac69a9147e", - "sha256:f97e83fa6c25693c7a35de154681fcc257c1c41b38beb0304b9c4d2d9e164479", - "sha256:f9d0c5c045a3ca9bedfc35dca8526798eb91a07aa7a2c0fee134c6c6f321cbd7", - "sha256:ff6f3db31555657f3163b15a6b7c6938d08df7adbfc9dd13d9d19edad678f1e8" - ], - "version": "==3.0.1" + "sha256:04afa6387e2b282cf78ff3dbce20f0cc071c12dc8f685bd40960cc68644cfea6", + "sha256:04eefcee095f58eaabe6dc3cc2262f3bcd776d2c67005880894f447b3f2cb9c1", + "sha256:0be65ccf618c1e7ac9b849c315cc2e8a8751d9cfdaa43027d4f6624bd587ab7e", + "sha256:0c95f12b74681e9ae127728f7e5409cbbef9cd914d5896ef238cc779b8152373", + "sha256:0ca564606d2caafb0abe6d1b5311c2649e8071eb241b2d64e75a0d0065107e62", + "sha256:10c93628d7497c81686e8e5e557aafa78f230cd9e77dd0c40032ef90c18f2230", + "sha256:11d117e6c63e8f495412d37e7dc2e2fff09c34b2d09dbe2bee3c6229577818be", + "sha256:11d3bcb7be35e7b1bba2c23beedac81ee893ac9871d0ba79effc7fc01167db6c", + "sha256:12a2b561af122e3d94cdb97fe6fb2bb2b82cef0cdca131646fdb940a1eda04f0", + "sha256:12d1a39aa6b8c6f6248bb54550efcc1c38ce0d8096a146638fd4738e42284448", + "sha256:1435ae15108b1cb6fffbcea2af3d468683b7afed0169ad718451f8db5d1aff6f", + "sha256:1c60b9c202d00052183c9be85e5eaf18a4ada0a47d188a83c8f5c5b23252f649", + "sha256:1e8fcdd8f672a1c4fc8d0bd3a2b576b152d2a349782d1eb0f6b8e52e9954731d", + "sha256:20064ead0717cf9a73a6d1e779b23d149b53daf971169289ed2ed43a71e8d3b0", + "sha256:21fa558996782fc226b529fdd2ed7866c2c6ec91cee82735c98a197fae39f706", + "sha256:22908891a380d50738e1f978667536f6c6b526a2064156203d418f4856d6e86a", + "sha256:3160a0fd9754aab7d47f95a6b63ab355388d890163eb03b2d2b87ab0a30cfa59", + "sha256:322102cdf1ab682ecc7d9b1c5eed4ec59657a65e1c146a0da342b78f4112db23", + "sha256:34e0a2f9c370eb95597aae63bf85eb5e96826d81e3dcf88b8886012906f509b5", + "sha256:3573d376454d956553c356df45bb824262c397c6e26ce43e8203c4c540ee0acb", + "sha256:3747443b6a904001473370d7810aa19c3a180ccd52a7157aacc264a5ac79265e", + "sha256:38e812a197bf8e71a59fe55b757a84c1f946d0ac114acafaafaf21667a7e169e", + "sha256:3a06f32c9634a8705f4ca9946d667609f52cf130d5548881401f1eb2c39b1e2c", + "sha256:3a5fc78f9e3f501a1614a98f7c54d3969f3ad9bba8ba3d9b438c3bc5d047dd28", + "sha256:3d9098b479e78c85080c98e1e35ff40b4a31d8953102bb0fd7d1b6f8a2111a3d", + "sha256:3dc5b6a8ecfdc5748a7e429782598e4f17ef378e3e272eeb1340ea57c9109f41", + "sha256:4155b51ae05ed47199dc5b2a4e62abccb274cee6b01da5b895099b61b1982974", + "sha256:49919f8400b5e49e961f320c735388ee686a62327e773fa5b3ce6721f7e785ce", + "sha256:53d0a3fa5f8af98a1e261de6a3943ca631c526635eb5817a87a59d9a57ebf48f", + "sha256:5f008525e02908b20e04707a4f704cd286d94718f48bb33edddc7d7b584dddc1", + "sha256:628c985afb2c7d27a4800bfb609e03985aaecb42f955049957814e0491d4006d", + "sha256:65ed923f84a6844de5fd29726b888e58c62820e0769b76565480e1fdc3d062f8", + "sha256:6734e606355834f13445b6adc38b53c0fd45f1a56a9ba06c2058f86893ae8017", + "sha256:6baf0baf0d5d265fa7944feb9f7451cc316bfe30e8df1a61b1bb08577c554f31", + "sha256:6f4f4668e1831850ebcc2fd0b1cd11721947b6dc7c00bf1c6bd3c929ae14f2c7", + "sha256:6f5c2e7bc8a4bf7c426599765b1bd33217ec84023033672c1e9a8b35eaeaaaf8", + "sha256:6f6c7a8a57e9405cad7485f4c9d3172ae486cfef1344b5ddd8e5239582d7355e", + "sha256:7381c66e0561c5757ffe616af869b916c8b4e42b367ab29fedc98481d1e74e14", + "sha256:73dc03a6a7e30b7edc5b01b601e53e7fc924b04e1835e8e407c12c037e81adbd", + "sha256:74db0052d985cf37fa111828d0dd230776ac99c740e1a758ad99094be4f1803d", + "sha256:75f2568b4189dda1c567339b48cba4ac7384accb9c2a7ed655cd86b04055c795", + "sha256:78cacd03e79d009d95635e7d6ff12c21eb89b894c354bd2b2ed0b4763373693b", + "sha256:80d1543d58bd3d6c271b66abf454d437a438dff01c3e62fdbcd68f2a11310d4b", + "sha256:830d2948a5ec37c386d3170c483063798d7879037492540f10a475e3fd6f244b", + "sha256:891cf9b48776b5c61c700b55a598621fdb7b1e301a550365571e9624f270c203", + "sha256:8f25e17ab3039b05f762b0a55ae0b3632b2e073d9c8fc88e89aca31a6198e88f", + "sha256:9a3267620866c9d17b959a84dd0bd2d45719b817245e49371ead79ed4f710d19", + "sha256:a04f86f41a8916fe45ac5024ec477f41f886b3c435da2d4e3d2709b22ab02af1", + "sha256:aaf53a6cebad0eae578f062c7d462155eada9c172bd8c4d250b8c1d8eb7f916a", + "sha256:abc1185d79f47c0a7aaf7e2412a0eb2c03b724581139193d2d82b3ad8cbb00ac", + "sha256:ac0aa6cd53ab9a31d397f8303f92c42f534693528fafbdb997c82bae6e477ad9", + "sha256:ac3775e3311661d4adace3697a52ac0bab17edd166087d493b52d4f4f553f9f0", + "sha256:b06f0d3bf045158d2fb8837c5785fe9ff9b8c93358be64461a1089f5da983137", + "sha256:b116502087ce8a6b7a5f1814568ccbd0e9f6cfd99948aa59b0e241dc57cf739f", + "sha256:b82fab78e0b1329e183a65260581de4375f619167478dddab510c6c6fb04d9b6", + "sha256:bd7163182133c0c7701b25e604cf1611c0d87712e56e88e7ee5d72deab3e76b5", + "sha256:c36bcbc0d5174a80d6cccf43a0ecaca44e81d25be4b7f90f0ed7bcfbb5a00909", + "sha256:c3af8e0f07399d3176b179f2e2634c3ce9c1301379a6b8c9c9aeecd481da494f", + "sha256:c84132a54c750fda57729d1e2599bb598f5fa0344085dbde5003ba429a4798c0", + "sha256:cb7b2ab0188829593b9de646545175547a70d9a6e2b63bf2cd87a0a391599324", + "sha256:cca4def576f47a09a943666b8f829606bcb17e2bc2d5911a46c8f8da45f56755", + "sha256:cf6511efa4801b9b38dc5546d7547d5b5c6ef4b081c60b23e4d941d0eba9cbeb", + "sha256:d16fd5252f883eb074ca55cb622bc0bee49b979ae4e8639fff6ca3ff44f9f854", + "sha256:d2686f91611f9e17f4548dbf050e75b079bbc2a82be565832bc8ea9047b61c8c", + "sha256:d7fc3fca01da18fbabe4625d64bb612b533533ed10045a2ac3dd194bfa656b60", + "sha256:dd5653e67b149503c68c4018bf07e42eeed6b4e956b24c00ccdf93ac79cdff84", + "sha256:de5695a6f1d8340b12a5d6d4484290ee74d61e467c39ff03b39e30df62cf83a0", + "sha256:e0ac8959c929593fee38da1c2b64ee9778733cdf03c482c9ff1d508b6b593b2b", + "sha256:e1b25e3ad6c909f398df8921780d6a3d120d8c09466720226fc621605b6f92b1", + "sha256:e633940f28c1e913615fd624fcdd72fdba807bf53ea6925d6a588e84e1151531", + "sha256:e89df2958e5159b811af9ff0f92614dabf4ff617c03a4c1c6ff53bf1c399e0e1", + "sha256:ea9f9c6034ea2d93d9147818f17c2a0860d41b71c38b9ce4d55f21b6f9165a11", + "sha256:f645caaf0008bacf349875a974220f1f1da349c5dbe7c4ec93048cdc785a3326", + "sha256:f8303414c7b03f794347ad062c0516cee0e15f7a612abd0ce1e25caf6ceb47df", + "sha256:fca62a8301b605b954ad2e9c3666f9d97f63872aa4efcae5492baca2056b74ab" + ], + "markers": "python_version >= '3.7'", + "version": "==3.1.0" }, "colorama": { "hashes": [ @@ -160,11 +157,11 @@ }, "furo": { "hashes": [ - "sha256:7cb76c12a25ef65db85ab0743df907573d03027a33631f17d267e598ebb191f7", - "sha256:d8008f8efbe7587a97ba533c8b2df1f9c21ee9b3e5cad0d27f61193d38b1a986" + "sha256:1cdf0730496f6ac0ecf394845fe55010539d987a3085f29d819e49a8e87da60a", + "sha256:6cf9a59fe2919693ecff6509a08229afa081583cbb5b81f59c3e755f3bd81d26" ], "index": "pypi", - "version": "==2022.12.7" + "version": "==2023.3.23" }, "idna": { "hashes": [ @@ -202,7 +199,7 @@ "sha256:5a35f8d1870171d9acc47b99612dc146129b631baf04970128b568f190d0cc30", "sha256:7c9a5e412688bc771c67432cbfebcdd686c93ce6484913dccf06cb5a0bea35a1" ], - "index": "pypi", + "markers": "python_version >= '3.7'", "version": "==2.2.0" }, "markupsafe": { @@ -263,11 +260,11 @@ }, "mdit-py-plugins": { "hashes": [ - "sha256:3278aab2e2b692539082f05e1243f24742194ffd92481f48844f057b51971283", - "sha256:4f1441264ac5cb39fa40a5901921c2acf314ea098d75629750c138f80d552cdf" + "sha256:ca9a0714ea59a24b2b044a1831f48d817dd0c817e84339f20e7889f392d77c4e", + "sha256:eee0adc7195e5827e17e02d2a258a2ba159944a0748f59c5099a4a27f78fcf6a" ], "markers": "python_version >= '3.7'", - "version": "==0.3.4" + "version": "==0.3.5" }, "mdurl": { "hashes": [ @@ -279,11 +276,11 @@ }, "myst-parser": { "hashes": [ - "sha256:61b275b85d9f58aa327f370913ae1bec26ebad372cc99f3ab85c8ec3ee8d9fb8", - "sha256:79317f4bb2c13053dd6e64f9da1ba1da6cd9c40c8a430c447a7b146a594c246d" + "sha256:502845659313099542bd38a2ae62f01360e7dd4b1310f025dd014dfc0439cdae", + "sha256:69fb40a586c6fa68995e6521ac0a525793935db7e724ca9bac1d33be51be9a4c" ], "index": "pypi", - "version": "==0.18.1" + "version": "==1.0.0" }, "packaging": { "hashes": [ @@ -298,7 +295,7 @@ "sha256:b3ed06a9e8ac9a9aae5a6f5dbe78a8a58655d17b43b93c078f094ddc476ae297", "sha256:fa7bd7bd2771287c0de303af8bfdfc731f51bd2c6a47ab69d117138893b82717" ], - "markers": "python_full_version >= '3.6.0'", + "markers": "python_version >= '3.6'", "version": "==2.14.0" }, "pyyaml": { @@ -344,7 +341,7 @@ "sha256:e61ceaab6f49fb8bdfaa0f92c4b57bcfbea54c09277b1b4f7ac376bfb7a7c174", "sha256:f84fbc98b019fef2ee9a1cb3ce93e3187a6df0b2538a651bfb890254ba9f90b5" ], - "markers": "python_full_version >= '3.6.0'", + "markers": "python_version >= '3.6'", "version": "==6.0" }, "requests": { @@ -380,11 +377,11 @@ }, "sphinx": { "hashes": [ - "sha256:060ca5c9f7ba57a08a1219e547b269fadf125ae25b06b9fa7f66768efb652d6d", - "sha256:51026de0a9ff9fc13c05d74913ad66047e104f56a129ff73e174eb5c3ee794b5" + "sha256:0dac3b698538ffef41716cf97ba26c1c7788dba73ce6f150c1ff5b4720786dd2", + "sha256:807d1cb3d6be87eb78a381c3e70ebd8d346b9a25f3753e9947e866b2786865fc" ], "index": "pypi", - "version": "==5.3.0" + "version": "==6.1.3" }, "sphinx-autobuild": { "hashes": [ @@ -434,6 +431,14 @@ "markers": "python_version >= '3.5'", "version": "==1.0.1" }, + "sphinxcontrib-mermaid": { + "hashes": [ + "sha256:15491c24ec78cf1626b1e79e797a9ce87cb7959cf38f955eb72dd5512aeb6ce9", + "sha256:fa3e5325d4ba395336e6137d113f55026b1a03ccd115dc54113d1d871a580466" + ], + "index": "pypi", + "version": "==0.8.1" + }, "sphinxcontrib-qthelp": { "hashes": [ "sha256:4c33767ee058b70dba89a6fc5c1892c0d57a54be67ddd3e7875a18d14cba5a72", @@ -467,21 +472,13 @@ "markers": "python_version > '2.7'", "version": "==6.2" }, - "typing-extensions": { - "hashes": [ - "sha256:5cb5f4a79139d699607b3ef622a1dedafa84e115ab0024e0d9c044a9479ca7cb", - "sha256:fb33085c39dd998ac16d1431ebc293a8b3eedd00fd4a32de0ff79002c19511b4" - ], - "markers": "python_version >= '3.7'", - "version": "==4.5.0" - }, "urllib3": { "hashes": [ - "sha256:076907bf8fd355cde77728471316625a4d2f7e713c125f51953bb5b3eecf4f72", - "sha256:75edcdc2f7d85b137124a6c3c9fc3933cdeaa12ecb9a6a959f22797a0feca7e1" + "sha256:8a388717b9476f934a21484e8c8e61875ab60644d29b9b39e11e4b9dc1c6b305", + "sha256:aa751d169e23c7479ce47a0cb0da579e3ede798f994f5816a74e4f4500dcea42" ], "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3, 3.4, 3.5'", - "version": "==1.26.14" + "version": "==1.26.15" } } } diff --git a/documentation/conf.py b/documentation/conf.py index 6dfa216b051..4c34a732e59 100644 --- a/documentation/conf.py +++ b/documentation/conf.py @@ -27,7 +27,7 @@ def add_ext_to_path(): # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = ["myst_parser", "link_issues"] +extensions = ["myst_parser", "sphinxcontrib.mermaid", "link_issues"] myst_heading_anchors = 6 # Add anchors to all headers, this is disabled by default. source_suffix = {".rst": "restructuredtext", ".md": "markdown"} diff --git a/documentation/index.md b/documentation/index.md index 5fc56893b22..4dde54ef98d 100644 --- a/documentation/index.md +++ b/documentation/index.md @@ -25,7 +25,7 @@ use the Openverse API, you should instead refer to the ## Table of contents ```{toctree} -:maxdepth: 2 +:maxdepth: 3 guides/index reference/index diff --git a/documentation/reference/decision_making/additional_practices.md b/documentation/reference/decision_making/additional_practices.md new file mode 100644 index 00000000000..f91f4942150 --- /dev/null +++ b/documentation/reference/decision_making/additional_practices.md @@ -0,0 +1,156 @@ +# Additional practices + +The goal of the practices described in this document are to help the team adhere +to the general guidelines of the +[decision-making process](./process_description.md) without overburdening +participants with too many discussions. + +## Current-round call out + +In the PR description or top-post of a GitHub discussion, discussion leaders +should include the following text: + +```md +This discussion is following the Openverse decision-making process. Information +about this process can be found +[on the Openverse documentation site](https://docs.openverse.org/reference/decision_making.html). +Requested reviewers or participants will be following this process. If you are +being asked to give input on a specific detail, you do not need to familiarise +yourself with the process and follow it. + +## Current round + +This discussion is currently in the **{Clarification, Revision, Decision, +Continued Revision} round**. +``` + +When a round ends, discussion leaders should leave a comment announcing the next +round along with the length of time allotted for it. + +## Discussion dashboard + +The +[discussion dashboard is implemented as a GitHub project](https://github.com/orgs/WordPress/projects/79/views/1) +for tracking the different rounds of a proposal. Proposal authors are expected +to correctly add and update proposals as they move through the different rounds +of discussion. This dashboard is used to +[help ensure we do not assign contributors to more than two discussions in parallel](#minimising-parallel-discussions), +so it is imperative that we maintain its accuracy. + +Each discussion should be tracked as a single card, with issues removed from the +"Pending proposal" column if a GitHub PR is opened. If a GitHub discussion is +used for the proposal, because those cannot be represented in GitHub project +boards, the issue should be used to track the status through the columns. + +This dashboard also serves as a record of decisions made on the team since the +dashboard's inception. Historical decisions that happened before the dashboard +started being used are not documented there. + +### Column descriptions + +For the most part, the columns correspond 1-to-1 with rounds of the Openverse +consent decision-making process. However, the following columns are unique and +bear explanation: + +- "Proposal requested": This column is meant for requested proposals or + discussions for which no formal proposal yet exists. This column should be + populated by the issues that document the request. +- "Discussion pending": This column is meant for proposals that have been + written, but cannot yet start the decision-making process (likely due to + contributor unavailability). + +## Minimising parallel discussions + +In the past, Openverse maintainers have been prone to feeling overwhelmed or +over encumbered by too many ongoing discussions demanding their attention. The +following practices are meant to mitigate the chances of this happening by +creating tools and processes for keep the number of active discussions per +participant to 2 or fewer. + +### Checking the dashboard + +Before requesting participation from specific people on a discussion, check the +[discussion dashboard](#discussion-dashboard) to ensure they're not already +involved in 2 ongoing discussions. If specific participants are required for a +given proposal (due to the relevance of their expertise in the proposal), then +you may open the proposal, but it should be left in the "pending discussion" +column. + +Tips for checking the dashboard and not accidentally over-encumbering people: + +- Check for discussions in the "pending discussion" column. If someone is + already assigned to discussions there, then know that any new discussions that + _must_ involve them will need to be triaged with the other discussion +- If a discussion could happen synchronously (if all participants have time + available), then you may be able to pull people in who are waiting for a + discussion to restart during the revision round, even if they're already + participating in the discussion + +In either case, it is still courteous to check with the individuals and make it +clear that they can push the discussion to someone else (provided they're not a +necessary subject-matter expert). + +### Project level process discussions + +Because project level process discussions usually effect all maintainers and +sometimes other contributors, they naturally garner the expectation of +involvement from broader sets of people than technical discussions. In addition +to the guidelines above for general discussions, we need additional special +guidelines to ensure we do not become over encumbered with process discussions +specifically. In particular, retrospectives may give rise to several discussions +that need to happen at once. In these cases, and others where process +discussions begin to dominate the discussion backlog, we'll need to triage +discussions. If discussions truly need the involvement of the entire team, we +can follow two processes: + +1. Put (and prioritise) the discussions into the "proposal requested" column of + the discussion dashboard and only allow one team-wide discussion to occur at + a time. Limiting this to 1 allows other non-team-wide discussions to also + happen at the same time without flooding the discussion board with team-wide + discussions and halting other, smaller, often technical discussions. +2. Split the group into groups of three or four people who can participate in + different parts of the discussion. This is useful if there are multiple + time-sensitive discussions and could lead to synchronous "lightening process" + meetings to make faster decisions and reduce the ongoing discussion burden on + team members. Even in this case, limit to 1 ongoing team-wide process + discussion per group of contributors. This is less useful if everyone on the + team wishes to give input in the discussion, although people are free to + asynchronously give input before the fact. + +For both, we will aim to limit the process discussions to one discussion at a +time for any given team member. This is recommended to avoid discussion burn out +as I think I've observed process discussions feeling much heavier weight and +burdensome than technical discussions. It also makes sure there is still room +for team members to be involved in one other separate technical discussion and +feel like they can still focus on their other work duties. + +## Speeding up decision-making + +The base process should help the Openverse project make decisions more quickly +and effectively. However, the following additional practices are available to +help move things along at an even faster clip, if so desired. + +### "Shortcutting" a round + +At any point during a round, any participant may say something along the lines +of "no (further) discussion needed on my part" in order to short-cut their +participation in the round. If all participants are finished sharing their part +in a given round, the author can choose to move to the next round, even if the +time period for the round has not been completed. This can be particularly +helpful for simpler discussions. + +### Going synchronous + +If all the participants of a particular discussion are able to participate in a +synchronous decision-making process, they may elect to do so. This can be +particularly useful for relatively small but impactful decisions where the +discussion periods would unnecessarily drag the process out. In these cases, +participants should hold a synchronous conversation with the understanding that +someone will take notes for each round, recording the feedback shared. **The +notes should be shared afterwards in the original proposal venue and should +include explicit headings per round.** If necessary, the synchronous discussion +can be broken into two separate sections to allow time for revision. + +Even in these cases, however, the text of the proposal should still be written +in a GitHub PR or discussion and available for all participants to read _before_ +the lightening process. diff --git a/documentation/reference/decision_making/how_to_use.md b/documentation/reference/decision_making/how_to_use.md new file mode 100644 index 00000000000..e7796f99652 --- /dev/null +++ b/documentation/reference/decision_making/how_to_use.md @@ -0,0 +1,49 @@ +# How to follow the process in different settings + +The team has agreed to use GitHub for all discussions, with links shared on the +[WordPress Make Openverse blog](https://make.wordpress.org/openverse/) to help +visibility for certain discussions. + +There are two tools in GitHub that can be used for conducting a discussion: PRs +and GitHub Discussions. We do not use GitHub issues because they do not allow +for threading. + +## PRs + +GitHub PRs are used for project proposals, implementation planning RFCs, and +other proposals that will be documented as Markdown files in the repository. + +GitHub PRs have the following ways of interacting with comments: + +- Inline comments on specific lines of text or code + - These allow opening "threads" and can be resolved +- General PR comments +- Review comments + +Each of these can serve their own purposes: + +- Inline comments + - These are perfect to supplement the clarification and decision rounds. If is + needed for a specific part of the proposal (rather than a more general + clarification), participants can leave their comments directly on the + relevant part of the proposal. Similarly, blockers specific to one part of + the proposal can be left as inline comments attached to a review requesting + changes. +- General PR comments + - For comments about the proposal in general like broad questions or problems. + - In addition to the PR description, the author of the PR will also create a + new top-level PR comment when a new round starts. +- Review comments + - These should be used in the decision round. Leave an approving review if you + have no blockers or "request changes" if you have a blocker. Attach inline + comments as needed in either case. + +## GitHub Discussions + +Because the format is slightly more limited than PRs, we will have a top-level +comment per round created by the author. Responses from participants should be +contained within the thread for each round. However, blockers during the +decision round should be raised as individual threads. The author will create a +top-level comment closing the previous round and opening the subsequent round. +If the proposal goes into continued revision, the discussion for addressing a +blocker can happen in the thread identifying the blocker. diff --git a/documentation/reference/decision_making/index.md b/documentation/reference/decision_making/index.md new file mode 100644 index 00000000000..a9816820181 --- /dev/null +++ b/documentation/reference/decision_making/index.md @@ -0,0 +1,16 @@ +# Openverse Decision-Making Process + +This process is loosely based on the Sociocratic "consent decision-making" +model, but is heavily adapted for an asynchronous context. The purpose of this +process is to help contributors to the Openverse project make expedient +decisions. That is, decisions that are both "good enough for now" and also made +quickly. In many ways, this process is a refinement on what was already being +practised, but with clearer expectations about time and feedback expression. + +```{toctree} +:maxdepth: 2 + +process_description +additional_practices +how_to_use +``` diff --git a/documentation/reference/decision_making/process_description.md b/documentation/reference/decision_making/process_description.md new file mode 100644 index 00000000000..c072a5da4c4 --- /dev/null +++ b/documentation/reference/decision_making/process_description.md @@ -0,0 +1,202 @@ +# Process description + +## Terms + +- "Participants": The author, all requested reviewers, and any additional + discussion participants. +- "Problem": A problematic aspect of the proposed solution, whether objective or + subjective. +- "Objective problem": A problem that does not depend on an individual's + perspective, i.e., something illegal, impossible, or too expensive. +- "Subjective problem": A problem regarding a matter of preference, e.g., a + choice between two roughly equivalent and usable tools. +- "Blocker": A problem with a proposed solution that would cause lasting harm to + the project or its contributors. +- "Fixable blocker": A blocker that can be addressed by revising the proposal. +- "Unworkable blocker": A blocker that cannot be addressed by revising the + proposal. In other words, a problem that requires an entirely new proposal to + be addressed. + +## Process overview + +The process is split into a series of rounds with broad expectations explained +below. Each step has a particular goal that participants should keep in mind. +The decision and continued revision round can repeat as many times as needed, at +the discretion of the participants. + +| Round | Suggested span | Goal | +| ----------------------------------------------------- | ------------------- | ----------------------------------------------------------------------------- | +| [Clarification round](#clarification-round) | 5 days | Clarify the proposal; share initial thoughts | +| [Revision round](#revision-round) | Author's discretion | Update the text of the proposal to reflect the outcome of the previous round | +| [Decision round](#decision-round) | 3 days | Decide whether the proposal can be implemented as is | +| [Continued revision round](#continued-revision-round) | Author's discretion | Work with participants to revise the text of the proposal to address blockers | +| [Approval](#approval) | N/A | Mark as approved and create issues to implement the proposal | +| [Tabling](#tabling) | N/A | Indicate that a proposal will not be implemented | + +### Time spans + +The suggested spans are just that: suggestions. If a particular proposal needs +more time for any reason, participants should note that and extend the round +duration. If reviewers are taken away from reviewing a proposal due to +extenuating circumstances like a production incident they need to be involved +in, they should note their unavailability on the discussion as soon as possible. +This expectation to notify of course does not apply if someone is taken away to +deal with life circumstances or other unexpected time AFK. + +In any case, participants will work together to decide whether the proposal can +wait or if another person should be requested to replace the unavailable person. + +Additionally, participants should try to maintain accountability to the +agreed-upon time spans. This means responding in a timely manner within the +window provided, understanding that authors will also need time to respond to +feedback, and following the practice described above to make explicit when they +will not be able to do so. + +### Diagram + +```{mermaid} +flowchart TD + A[Proposal] --> B(Clarification Round) + B -->|"Time: ~5 days"| C("Revision Round (if needed)") + C -->|Time: As needed/estimated by author| D(Decision Round) + D -.->|Fixable blockers identified| E + E("Continued Revision Round (if needed)") + D -.->|No blockers identified| H + E --> D + D -.->|Unworkable blockers identified| G + G[Proposal tabled] -->|New proposal needed| A + H[Proposal approved] --> I((End)) +``` + +## Round descriptions + +> **Note** +> +> While each round includes discussion guidelines and a description of purpose, +> these are flexible. Participants should use their discretion and should adapt +> the process as needed for any given proposal. If a blocker is apparent at the +> start of a discussion, do not wait for the decision round to share it. If a +> solution is known to be illegal or impossible, share that as early as +> possible. Additionally, if a proposal document has a structural issue that +> belies clarification, authors may revise to fix the proposal as soon as the +> problem is identified. + +### Clarification round + +The goal of this round is for participants to clarify the proposed solution and +share their initial thoughts and feelings about the proposal. We especially +encourage reviewers to look for opportunities to share explicit praise where it +is due. The broad focus should be on ensuring all participants understand what +is being proposed and why other potential solutions, if any reasonable ones +exist, were not chosen. By ensuring participants understand a proposal and that +the author has a chance to revise any initial problems identified during +clarification, we hope to cultivate an increased sense of trust: both that +reviewers are reviewing in good faith and that the author's work is respected +and understood to be the best attempt at proposing a solution to the problem. + +During this round authors should refrain as much as possible from making large +changes to the proposal other than editorial/proofreading ones. This is to help +minimise confusion caused by a proposal that is changing while also being +reviewed for clarification. + +#### Purpose + +Proposals must all include an explicit "purpose". Often these are informed by +the needs of a particular project associated with the proposal or with a +requested discussion as the result of a retrospective or other self-feedback +mechanism. However, contributors may, at their discretion, raise proposals for +discussion that do not have prior conversations. In these cases, the +clarification round is also understood to include an evaluation and +clarification of the purpose of the proposal. For regularly requested proposals, +however, the purpose is taken to be accepted and should not be the focus of the +discussion. + +### Revision round + +The goal of this round is for authors to incorporate the feedback received in +the clarification round. At this time, any changes can be made to the proposal +document. + +When the round starts, the author should share how long they will need to finish +revising the document. This helps give clear expectations for reviewers for when +they will need to return to the discussion and also establishes accountability +on the part of the author. Together these help prevent discussions from dragging +on or having an indefinite "slump" during revision. + +### Decision round + +The goal of this round is for the participants to decide whether the proposal +can be implemented in its current form. The focus of this round should be to +carefully consider any problems present with the proposal and decide whether +they are blockers or whether they can be iterated on after the initial +implementation. If further clarification is needed about an aspect of the +proposal that could cause harm, that is automatically considered to be a +blocker. If problem is a blocker, then reviewers should request changes to +address the issue, if it can be addressed. If the blocking issue cannot be +addressed (it is "unworkable"), then the proposal is tabled, though this should +be rare. Participants should all work together to help identify whether an issue +is truly a blocker or whether it is something that can be iterated on. Objective +problems should be given priority, whereas addressing subjective problems should +err on the side of avoiding the need for large revisions. If a proposal is +founded upon the usage of one tool, but another equivalent tool is also +available, it is up to the author whether they feel it is worth reworking the +proposal to use the other tool to appease the preference of the reviewer. + +The idea behind this specific structure is two-fold: + +- It acknowledges that Openverse maintainers are capable contributors and more + often than propose solutions that are workable, even if they sometimes need + revisions +- It makes explicit the expectation that we are looking for "good enough for + now" solutions that can be iterated and improved on afterwards + +Both of these help decision-making go faster, while also carefully identifying +what aspects of a proposal may need special attention either during +implementation or after the fact. Both of these are also, however, not steadfast +rules. Everyone makes mistakes and everyone can miss big or small details of a +problem that lead them down the wrong path. Working together as a team, all the +participants are tasked with deciding whether a solution is feasible and finding +ways to resolve blockers. + +The suggested time span for the decision round is shorter for two reasons: + +1. To encourage front-loading discussion during the clarification round +1. To acknowledge that the goal of the decision round is to decide whether the + proposal can be implemented and iterated on or whether it has blockers + +The decision round isn't necessarily another discussion round, aside from +deliberating about whether certain problems are blockers or not. Three days is +the suggested span because it allows time for at least one back and forth +between author and reviewers to decide whether problems are blockers. Further +discussion about the problems should continue during the subsequent revision +round between the person who identified the blocker and the proposal author. + +### Continued revision round + +If fixable blocking problems are identified during the decision round, the +author and participants should work together to revise the proposal to address +the problem so that it is no longer a blocker. This can be done either by +changing the proposal so that the problem no longer exists at all, or so that +the potential harm caused by the problem is mitigated. In other words, the +problem could still exist (whether objectively or subjectively), but the harm +caused by it is either no longer possible or sufficient guardrails or safety +measures have been taken to mitigate and address the harm or make it reversible. + +After the revision is complete, the proposal goes back to the decision round. +The decision round and the continued revision round can repeat as many times as +needed until a proposal no longer has blockers. + +### Proposal approval + +Proposals are approved when the requested reviewers have voiced approval and +there are no outstanding blockers. + +At this stage, authors will create any new milestones or issues to track the +work needed to implement the accepted solution. Milestones should be linked in +the proposal text. + +### Proposal tabling + +Proposals are tabled when unworkable blockers are identified. In cases where a +proposal was requested as part of a project, a new proposal should be requested +that approaches the problem in a new way to avoid causing the same problems. diff --git a/documentation/reference/index.md b/documentation/reference/index.md index d480d87144c..48e2aa7d454 100644 --- a/documentation/reference/index.md +++ b/documentation/reference/index.md @@ -1,9 +1,10 @@ # Reference ```{toctree} -:maxdepth: 1 +:maxdepth: 2 github_contribution_practices +decision_making/index dev_flow api/index frontend/index