From cfd96f4ca3b35e381c285923c09edbe5cad9d801 Mon Sep 17 00:00:00 2001 From: Lily Date: Thu, 25 Apr 2024 10:09:19 -0700 Subject: [PATCH 1/7] Replace flake8/isort/black with ruff. [Ruff](https://github.com/astral-sh/ruff) is a newer project from only a few years ago that does all the things flake8/isort/black does, but in one package, and is much faster. I think standardizing on ruff for new projects would help have less tools to run and set up, and also reduce cycle time by making it run anywhere from slightly to much faster than flake8 depending on the size of the project. --- content/engineering/languages-runtimes/python.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/content/engineering/languages-runtimes/python.md b/content/engineering/languages-runtimes/python.md index b0727d1e..56b5dc18 100644 --- a/content/engineering/languages-runtimes/python.md +++ b/content/engineering/languages-runtimes/python.md @@ -47,9 +47,17 @@ Finally, in an effort to ensure our deployments are repeatable, our code **stand (though this is only a partial solution) ## Style -Our **standard** tool for ensuring consistency across Python code bases is [flake8](http://flake8.pycqa.org/en/latest/). Its **default** settings are a good first step, as is using its [integration with isort](https://pypi.python.org/pypi/flake8-isort) for import order. We **suggest** investigating flake8's [plugin ecosystem](https://pypi.python.org/pypi?%3Aaction=search&term=flake8&submit=search) for more functionality. -Use [Black](https://black.readthedocs.io/en/stable/) for automatic code formatting. +Our **standard** tool for ensuring consistency across Python code bases is +[Ruff](https://github.com/astral-sh/ruff). Its **default** settings are a good +first step. + +It includes syntax checking (previously under +[flake8](http://flake8.pycqa.org/en/latest/)), import ordering (previously under +[isort](https://pypi.python.org/pypi/flake8-isort)), and automatic code +formatting (same defaults as [Black](https://black.readthedocs.io/en/stable/)), +but all in one package and runs much faster than previous programs. In older +projects these tools may still be being used. Using Code Climate to measure complexity scores (by way of [radon](https://pypi.python.org/pypi/radon)) is also a reasonable **default** to ensure you see potentially confounding functions and classes. From a50b820fd1c553daf31282a6a0c901d0176284c2 Mon Sep 17 00:00:00 2001 From: Lily Date: Thu, 25 Apr 2024 10:11:17 -0700 Subject: [PATCH 2/7] replace whitelist with allowlist --- content/engineering/languages-runtimes/python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/engineering/languages-runtimes/python.md b/content/engineering/languages-runtimes/python.md index 56b5dc18..3f40cd65 100644 --- a/content/engineering/languages-runtimes/python.md +++ b/content/engineering/languages-runtimes/python.md @@ -76,6 +76,6 @@ The Python ecosystem is large and full of alternative solutions to similar probl ## Type support Python 3.5 and beyond have had partial support for static type hints. Static typing can both make code authors' intent clearer and reduce the number of bugs through static analysis. It's also notorious for slowing down the pace of prototyping and requiring a great deal of boiler-plate. -Given this state, we believe it's reasonable to **default** to using type annotations when they make your intent clearer (i.e. as a form of documentation). We **suggest** using a static analysis tool (such as [mypy](http://mypy.readthedocs.io/en/latest/)) to catch logic bugs, but only where it's practical. Consider a white-list of files to run against. +Given this state, we believe it's reasonable to **default** to using type annotations when they make your intent clearer (i.e. as a form of documentation). We **suggest** using a static analysis tool (such as [mypy](http://mypy.readthedocs.io/en/latest/)) to catch logic bugs, but only where it's practical. Consider an allowlist of files to run against. [Django]: https://www.djangoproject.com/ From 666a756905d7557694d75bcf015514a58db42cbc Mon Sep 17 00:00:00 2001 From: Lily Date: Thu, 25 Apr 2024 10:16:55 -0700 Subject: [PATCH 3/7] add link to poetry as another package manager option --- content/engineering/languages-runtimes/python.md | 1 + 1 file changed, 1 insertion(+) diff --git a/content/engineering/languages-runtimes/python.md b/content/engineering/languages-runtimes/python.md index 3f40cd65..ad4c85c7 100644 --- a/content/engineering/languages-runtimes/python.md +++ b/content/engineering/languages-runtimes/python.md @@ -41,6 +41,7 @@ When using [Django], we **default** to starting with the most recent [Long Term Otherwise, our **standard** practice is to use the latest release of our libraries when first installing. Security updates (as indicated by GitHub or Snyk) should be applied ASAP, but all libs should be updated at some routine interval (e.g. quarterly). Finally, in an effort to ensure our deployments are repeatable, our code **standards** require all dependencies (including dependencies' dependencies) be pinned to specific versions. This should also apply to the development environment (e.g. linters, testing tools, etc.) **Suggestions** for implementing that include +* [poetry](https://python-poetry.org/) * [pip-tools](https://github.com/jazzband/pip-tools)'s `pip-sync` * [pipenv](https://github.com/pypa/pipenv)'s `Pipfile.lock` * [vendoring dependencies](https://docs.cloudfoundry.org/buildpacks/python/index.html#vendoring) From 6ce023ad8ef7849c7f28848a49e1fbbc6025287a Mon Sep 17 00:00:00 2001 From: Lily Date: Thu, 25 Apr 2024 10:24:51 -0700 Subject: [PATCH 4/7] change ruff standard to a suggestion until it's more widely adopted --- .../engineering/languages-runtimes/python.md | 17 +++++++---------- 1 file changed, 7 insertions(+), 10 deletions(-) diff --git a/content/engineering/languages-runtimes/python.md b/content/engineering/languages-runtimes/python.md index ad4c85c7..1b5e189d 100644 --- a/content/engineering/languages-runtimes/python.md +++ b/content/engineering/languages-runtimes/python.md @@ -49,16 +49,13 @@ Finally, in an effort to ensure our deployments are repeatable, our code **stand ## Style -Our **standard** tool for ensuring consistency across Python code bases is -[Ruff](https://github.com/astral-sh/ruff). Its **default** settings are a good -first step. - -It includes syntax checking (previously under -[flake8](http://flake8.pycqa.org/en/latest/)), import ordering (previously under -[isort](https://pypi.python.org/pypi/flake8-isort)), and automatic code -formatting (same defaults as [Black](https://black.readthedocs.io/en/stable/)), -but all in one package and runs much faster than previous programs. In older -projects these tools may still be being used. +Our **standard** tool for ensuring consistency across Python code bases is [flake8](http://flake8.pycqa.org/en/latest/). Its **default** settings are a good first step, as is using its [integration with isort](https://pypi.python.org/pypi/flake8-isort) for import order. We **suggest** investigating flake8's [plugin ecosystem](https://pypi.python.org/pypi?%3Aaction=search&term=flake8&submit=search) for more functionality. + +Use [Black](https://black.readthedocs.io/en/stable/) for automatic code formatting. + +We **suggest** using [Ruff](https://github.com/astral-sh/ruff) instead as it +combines all of the above packages into one and runs faster, however this has +not yet been adopted widely across TTS yet. Using Code Climate to measure complexity scores (by way of [radon](https://pypi.python.org/pypi/radon)) is also a reasonable **default** to ensure you see potentially confounding functions and classes. From a009342261174c490ad893ecced47d867500ff0a Mon Sep 17 00:00:00 2001 From: Lily Date: Thu, 25 Apr 2024 10:28:46 -0700 Subject: [PATCH 5/7] remove superfluous newline --- content/engineering/languages-runtimes/python.md | 1 - 1 file changed, 1 deletion(-) diff --git a/content/engineering/languages-runtimes/python.md b/content/engineering/languages-runtimes/python.md index 1b5e189d..6ea13415 100644 --- a/content/engineering/languages-runtimes/python.md +++ b/content/engineering/languages-runtimes/python.md @@ -48,7 +48,6 @@ Finally, in an effort to ensure our deployments are repeatable, our code **stand (though this is only a partial solution) ## Style - Our **standard** tool for ensuring consistency across Python code bases is [flake8](http://flake8.pycqa.org/en/latest/). Its **default** settings are a good first step, as is using its [integration with isort](https://pypi.python.org/pypi/flake8-isort) for import order. We **suggest** investigating flake8's [plugin ecosystem](https://pypi.python.org/pypi?%3Aaction=search&term=flake8&submit=search) for more functionality. Use [Black](https://black.readthedocs.io/en/stable/) for automatic code formatting. From 27cf247af747a963e1af70c8d4deb52d1f338ac7 Mon Sep 17 00:00:00 2001 From: Lily Date: Thu, 25 Apr 2024 10:29:21 -0700 Subject: [PATCH 6/7] grab a few more whitelist->allowlist fixes while i'm in here --- content/engineering/security/content-security-policy.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/engineering/security/content-security-policy.md b/content/engineering/security/content-security-policy.md index 4b4cba0a..27c020d3 100644 --- a/content/engineering/security/content-security-policy.md +++ b/content/engineering/security/content-security-policy.md @@ -119,11 +119,11 @@ However, there are scenarios in which you may want to use an inline content tag, Another potential issue is third-party libraries that automatically inject JavaScript and CSS into your HTML. If your project utilizes a library that does this, the only guaranteed solution is to use the `unsafe-inline` value when setting the `script-src` directive; this obviously defeats the purpose of having a CSP for your JavaScript. -If you must load external scripts inline and are not allowed to use the `unsafe-inline` keyword, you could also make a SHA hash of the script being included, and whitelist that in your content security policy. +If you must load external scripts inline and are not allowed to use the `unsafe-inline` keyword, you could also make a SHA hash of the script being included, and allowlist that in your content security policy. This technique will allow those scripts to load, with the following caveats: -* Each the time the third-party script changes, a new hash will have to be computed, and your policy's `script-src` whitelist will need to be updated +* Each the time the third-party script changes, a new hash will have to be computed, and your policy's `script-src` allowlist will need to be updated * Inline the SHAs of multiple scripts adds bloat to the policy, and increases the number of bytes needed to transmit the header to the browser. As each project has its own needs, you should always perform your own research on a per-project basis to determine the best way to handle third-party scripts! From 9174878d82fbabaf434b32d179907df0e86748a3 Mon Sep 17 00:00:00 2001 From: Lily Date: Thu, 25 Apr 2024 12:35:51 -0700 Subject: [PATCH 7/7] update wording on ruff suggestion low adoption could = dissuasion against, we want to be encouraging --- content/engineering/languages-runtimes/python.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/engineering/languages-runtimes/python.md b/content/engineering/languages-runtimes/python.md index 6ea13415..29de4625 100644 --- a/content/engineering/languages-runtimes/python.md +++ b/content/engineering/languages-runtimes/python.md @@ -52,9 +52,9 @@ Our **standard** tool for ensuring consistency across Python code bases is [flak Use [Black](https://black.readthedocs.io/en/stable/) for automatic code formatting. -We **suggest** using [Ruff](https://github.com/astral-sh/ruff) instead as it -combines all of the above packages into one and runs faster, however this has -not yet been adopted widely across TTS yet. +You are welcome to use [Ruff](https://github.com/astral-sh/ruff) instead as it +combines all of the above packages into one and runs faster. It may become our +standard in the future. Using Code Climate to measure complexity scores (by way of [radon](https://pypi.python.org/pypi/radon)) is also a reasonable **default** to ensure you see potentially confounding functions and classes.