diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index 71420dc..7d9cdca 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -8,4 +8,6 @@ justfile .editorconfig .gitignore -ruff.toml \ No newline at end of file +ruff.toml +pyproject.toml +poetry.lock diff --git a/.gitignore b/.gitignore index ac951d8..e48f5e3 100644 --- a/.gitignore +++ b/.gitignore @@ -77,6 +77,7 @@ junit/ # Quarto /.quarto/ +docs/.quarto/ # Website generation _site @@ -86,9 +87,14 @@ site # Local data files **/datafile/* +# Persistent storage should not be stored in git except for the markdown files +persistent_storage +!persistent_storage/**/*.md # Python Django *.log local_settings.py db.sqlite3 db.sqlite3-journal +# We'll disable migrations for now, until we have actual users +migrations diff --git a/.vscode/extensions.json b/.vscode/extensions.json index b725d21..c111b79 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -1,7 +1,6 @@ { // See https://go.microsoft.com/fwlink/?LinkId=827846 to learn about workspace recommendations. // Extension identifier format: ${publisher}.${name}. Example: vscode.csharp - // List of extensions which should be recommended for users of this workspace. "recommendations": [ "jebbs.plantuml", @@ -19,10 +18,10 @@ "vivaxy.vscode-conventional-commits", "charliermarsh.ruff", "pshaddel.conventional-branch", - "yy0931.vscode-sqlite3-editor" + "yy0931.vscode-sqlite3-editor", + "junstyle.vscode-django-support", + "monosans.djlint" ], // List of extensions recommended by VS Code that should not be recommended for users of this workspace. - "unwantedRecommendations": [ - - ] -} + "unwantedRecommendations": [] +} \ No newline at end of file diff --git a/.vscode/json.code-snippets b/.vscode/json.code-snippets index 8ac8249..fafcd72 100644 --- a/.vscode/json.code-snippets +++ b/.vscode/json.code-snippets @@ -36,7 +36,7 @@ "Insert YAML header for blogs": { "scope": "quarto,markdown", - "prefix": "yaml_blog", + "prefix": "post_yaml", "body": [ "---" "title: \"\"" @@ -44,6 +44,7 @@ "author: \"\"" "date: last-modified" "categories:" + " ${0:Type 'category_keywords' to insert categories}" "---" ], "description": "Insert YAML header for Quarto blog posts." @@ -112,55 +113,48 @@ // The idea is that we can insert this section and then delete the words we aren't interested in // If words are missing then they can be added to the document, and then also added to the code snippet // Much the same way that words can be added to the spell-check extension. - "Insert title section with list of category words": { - "scope": "quarto,markdown", - "prefix": "ttl_sec_cat", + "Insert list of category words": { + "scope": "quarto,markdown,yaml", + "prefix": "category_keywords", "body": [ - "---" - "title: \"\"" - "description: \"Our reasons for ...\"" - "author: \"\"" - "date: last-modified" - "categories:" - " - api" - " - backend" - " - blogs" - " - code snippets" - " - communication" - " - container" - " - contributing" - " - copyright" - " - culture" - " - database" - " - development" - " - documentation" - " - frontend" - " - github" - " - implementation" - " - installation" - " - licensing" - " - management" - " - markdown" - " - organization" - " - programming" - " - repositories" - " - reviewing" - " - software" - " - software architecture" - " - standardisation" - " - structure" - " - team work" - " - teamworking" - " - technology" - " - templates" - " - tools" - " - vs code" - " - web" - " - website" - " - workflow" - " - writing" - "---" + "- api" + "- backend" + "- blogs" + "- code snippets" + "- communication" + "- container" + "- contributing" + "- copyright" + "- culture" + "- database" + "- development" + "- documentation" + "- frontend" + "- github" + "- implementation" + "- installation" + "- licensing" + "- management" + "- markdown" + "- organization" + "- programming" + "- repositories" + "- reviewing" + "- software" + "- software architecture" + "- standardisation" + "- structure" + "- team work" + "- teamworking" + "- technology" + "- templates" + "- tools" + "- vs code" + "- web" + "- website" + "- workflow" + "- writing" ], - "description": "Insert title with category words" + "description": "Insert list of category words" } -} \ No newline at end of file +} diff --git a/.vscode/settings.json b/.vscode/settings.json index 5450c82..b5f7833 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -3,6 +3,9 @@ "editor.tabSize": 2, "editor.wordWrap": "off", "editor.formatOnSave": true, + "editor.codeActionsOnSave": { + "source.organizeImports": "always" + }, "git.autofetch": false, "quarto.visualEditor.markdownWrap": "column", "quarto.visualEditor.markdownWrapColumn": 72, @@ -23,5 +26,15 @@ "conventional-branch.format": "{Type}/{Branch}", "[python]": { "editor.defaultFormatter": "charliermarsh.ruff" - } -} \ No newline at end of file + }, + "[html][django-html]": { + "editor.defaultFormatter": "monosans.djlint" + }, + "python.defaultInterpreterPath": "${workspaceFolder}/.venv", + "python.languageServer": "Pylance", + "files.insertFinalNewline": true, + "cSpell.enableFiletypes": [ + "quarto" + ], + "cSpell.language": "en,en-GB", +} diff --git a/_extensions/seedcase-project/seedcase-theme/_extension.yml b/_extensions/seedcase-project/seedcase-theme/_extension.yml index bfcd2ea..f4c84b9 100644 --- a/_extensions/seedcase-project/seedcase-theme/_extension.yml +++ b/_extensions/seedcase-project/seedcase-theme/_extension.yml @@ -7,7 +7,7 @@ contributes: html: from: markdown+emoji theme: - - zephyr + - cosmo - theme.scss toc: true toc-location: right @@ -19,12 +19,17 @@ contributes: execute-dir: project website: + page-navigation: true + favicon: favicon/favicon.ico repo-branch: main repo-actions: [edit, issue, source] search: location: navbar type: overlay + navbar: + background: light + logo: logos/navbar-logo-seedcase-project.svg csl: vancouver.csl - format: seedcase-theme-html \ No newline at end of file + format: seedcase-theme-html diff --git a/_extensions/seedcase-project/seedcase-theme/android-chrome-192x192.png b/_extensions/seedcase-project/seedcase-theme/android-chrome-192x192.png new file mode 100644 index 0000000..75d92b2 Binary files /dev/null and b/_extensions/seedcase-project/seedcase-theme/android-chrome-192x192.png differ diff --git a/_extensions/seedcase-project/seedcase-theme/android-chrome-512x512.png b/_extensions/seedcase-project/seedcase-theme/android-chrome-512x512.png new file mode 100644 index 0000000..95bd906 Binary files /dev/null and b/_extensions/seedcase-project/seedcase-theme/android-chrome-512x512.png differ diff --git a/_extensions/seedcase-project/seedcase-theme/apple-touch-icon.png b/_extensions/seedcase-project/seedcase-theme/apple-touch-icon.png new file mode 100644 index 0000000..8bba016 Binary files /dev/null and b/_extensions/seedcase-project/seedcase-theme/apple-touch-icon.png differ diff --git a/_extensions/seedcase-project/seedcase-theme/favicon-16x16.png b/_extensions/seedcase-project/seedcase-theme/favicon-16x16.png new file mode 100644 index 0000000..1958ca5 Binary files /dev/null and b/_extensions/seedcase-project/seedcase-theme/favicon-16x16.png differ diff --git a/_extensions/seedcase-project/seedcase-theme/favicon-32x32.png b/_extensions/seedcase-project/seedcase-theme/favicon-32x32.png new file mode 100644 index 0000000..a30619e Binary files /dev/null and b/_extensions/seedcase-project/seedcase-theme/favicon-32x32.png differ diff --git a/_extensions/seedcase-project/seedcase-theme/favicon.ico b/_extensions/seedcase-project/seedcase-theme/favicon.ico new file mode 100644 index 0000000..b313616 Binary files /dev/null and b/_extensions/seedcase-project/seedcase-theme/favicon.ico differ diff --git a/_extensions/seedcase-project/seedcase-theme/favicon/android-chrome-192x192.png b/_extensions/seedcase-project/seedcase-theme/favicon/android-chrome-192x192.png new file mode 100644 index 0000000..5ae7983 Binary files /dev/null and b/_extensions/seedcase-project/seedcase-theme/favicon/android-chrome-192x192.png differ diff --git a/_extensions/seedcase-project/seedcase-theme/favicon/android-chrome-512x512.png b/_extensions/seedcase-project/seedcase-theme/favicon/android-chrome-512x512.png new file mode 100644 index 0000000..9340bcc Binary files /dev/null and b/_extensions/seedcase-project/seedcase-theme/favicon/android-chrome-512x512.png differ diff --git a/_extensions/seedcase-project/seedcase-theme/favicon/apple-touch-icon.png b/_extensions/seedcase-project/seedcase-theme/favicon/apple-touch-icon.png new file mode 100644 index 0000000..a5ffd2a Binary files /dev/null and b/_extensions/seedcase-project/seedcase-theme/favicon/apple-touch-icon.png differ diff --git a/_extensions/seedcase-project/seedcase-theme/favicon/favicon-16x16.png b/_extensions/seedcase-project/seedcase-theme/favicon/favicon-16x16.png new file mode 100644 index 0000000..7090200 Binary files /dev/null and b/_extensions/seedcase-project/seedcase-theme/favicon/favicon-16x16.png differ diff --git a/_extensions/seedcase-project/seedcase-theme/favicon/favicon-32x32.png b/_extensions/seedcase-project/seedcase-theme/favicon/favicon-32x32.png new file mode 100644 index 0000000..3a75b2c Binary files /dev/null and b/_extensions/seedcase-project/seedcase-theme/favicon/favicon-32x32.png differ diff --git a/_extensions/seedcase-project/seedcase-theme/favicon/favicon.ico b/_extensions/seedcase-project/seedcase-theme/favicon/favicon.ico new file mode 100644 index 0000000..bf7fbfa Binary files /dev/null and b/_extensions/seedcase-project/seedcase-theme/favicon/favicon.ico differ diff --git a/_extensions/seedcase-project/seedcase-theme/favicon/site.webmanifest b/_extensions/seedcase-project/seedcase-theme/favicon/site.webmanifest new file mode 100644 index 0000000..45dc8a2 --- /dev/null +++ b/_extensions/seedcase-project/seedcase-theme/favicon/site.webmanifest @@ -0,0 +1 @@ +{"name":"","short_name":"","icons":[{"src":"/android-chrome-192x192.png","sizes":"192x192","type":"image/png"},{"src":"/android-chrome-512x512.png","sizes":"512x512","type":"image/png"}],"theme_color":"#ffffff","background_color":"#ffffff","display":"standalone"} \ No newline at end of file diff --git a/_extensions/seedcase-project/seedcase-theme/logo.png b/_extensions/seedcase-project/seedcase-theme/logo.png new file mode 100644 index 0000000..ef7e7ee Binary files /dev/null and b/_extensions/seedcase-project/seedcase-theme/logo.png differ diff --git a/_extensions/seedcase-project/seedcase-theme/logos/au-logo.png b/_extensions/seedcase-project/seedcase-theme/logos/au-logo.png new file mode 100644 index 0000000..4c6625e Binary files /dev/null and b/_extensions/seedcase-project/seedcase-theme/logos/au-logo.png differ diff --git a/_extensions/seedcase-project/seedcase-theme/logos/flower-logo.svg b/_extensions/seedcase-project/seedcase-theme/logos/flower-logo.svg new file mode 100644 index 0000000..94be68d --- /dev/null +++ b/_extensions/seedcase-project/seedcase-theme/logos/flower-logo.svg @@ -0,0 +1,6 @@ + + + + + + diff --git a/_extensions/seedcase-project/seedcase-theme/logos/garden-logo.svg b/_extensions/seedcase-project/seedcase-theme/logos/garden-logo.svg new file mode 100644 index 0000000..6632d17 --- /dev/null +++ b/_extensions/seedcase-project/seedcase-theme/logos/garden-logo.svg @@ -0,0 +1,12 @@ + + + + + + + + + + + + diff --git a/_extensions/seedcase-project/seedcase-theme/logos/mjoelner-logo.svg b/_extensions/seedcase-project/seedcase-theme/logos/mjoelner-logo.svg new file mode 100644 index 0000000..ca3479f --- /dev/null +++ b/_extensions/seedcase-project/seedcase-theme/logos/mjoelner-logo.svg @@ -0,0 +1,10 @@ + + + + + + + + \ No newline at end of file diff --git a/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-community.svg b/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-community.svg new file mode 100644 index 0000000..5ecfdac --- /dev/null +++ b/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-community.svg @@ -0,0 +1,18 @@ + + + + + + + + + + + + + + + + + + diff --git a/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-decisions.svg b/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-decisions.svg new file mode 100644 index 0000000..563fc6f --- /dev/null +++ b/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-decisions.svg @@ -0,0 +1,17 @@ + + + + + + + + + + + + + + + + + diff --git a/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-design.svg b/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-design.svg new file mode 100644 index 0000000..fd2456a --- /dev/null +++ b/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-design.svg @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + diff --git a/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-flower.svg b/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-flower.svg new file mode 100644 index 0000000..2edb75b --- /dev/null +++ b/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-flower.svg @@ -0,0 +1,17 @@ + + + + + + + + + + + + + + + + + diff --git a/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-garden.svg b/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-garden.svg new file mode 100644 index 0000000..dbbbd60 --- /dev/null +++ b/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-garden.svg @@ -0,0 +1,20 @@ + + + + + + + + + + + + + + + + + + + + diff --git a/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-learn.svg b/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-learn.svg new file mode 100644 index 0000000..3f0023d --- /dev/null +++ b/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-learn.svg @@ -0,0 +1,13 @@ + + + + + + + + + + + + + diff --git a/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-project.svg b/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-project.svg new file mode 100644 index 0000000..d3b407c --- /dev/null +++ b/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-project.svg @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-propagate.svg b/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-propagate.svg new file mode 100644 index 0000000..eab9dc5 --- /dev/null +++ b/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-propagate.svg @@ -0,0 +1,21 @@ + + + + + + + + + + + + + + + + + + + + + diff --git a/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-sprout.svg b/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-sprout.svg new file mode 100644 index 0000000..610198c --- /dev/null +++ b/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-sprout.svg @@ -0,0 +1,17 @@ + + + + + + + + + + + + + + + + + diff --git a/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-team.svg b/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-team.svg new file mode 100644 index 0000000..b0c234c --- /dev/null +++ b/_extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-team.svg @@ -0,0 +1,10 @@ + + + + + + + + + + diff --git a/_extensions/seedcase-project/seedcase-theme/logos/nnf-logo.png b/_extensions/seedcase-project/seedcase-theme/logos/nnf-logo.png new file mode 100644 index 0000000..5ef703e Binary files /dev/null and b/_extensions/seedcase-project/seedcase-theme/logos/nnf-logo.png differ diff --git a/_extensions/seedcase-project/seedcase-theme/logos/propagate-logo.svg b/_extensions/seedcase-project/seedcase-theme/logos/propagate-logo.svg new file mode 100644 index 0000000..b30bf88 --- /dev/null +++ b/_extensions/seedcase-project/seedcase-theme/logos/propagate-logo.svg @@ -0,0 +1,6 @@ + + + + + + diff --git a/_extensions/seedcase-project/seedcase-theme/logos/rm-logo.svg b/_extensions/seedcase-project/seedcase-theme/logos/rm-logo.svg new file mode 100644 index 0000000..d782e8d --- /dev/null +++ b/_extensions/seedcase-project/seedcase-theme/logos/rm-logo.svg @@ -0,0 +1,25 @@ + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/_extensions/seedcase-project/seedcase-theme/logos/sdca-logo.png b/_extensions/seedcase-project/seedcase-theme/logos/sdca-logo.png new file mode 100644 index 0000000..adb5bae Binary files /dev/null and b/_extensions/seedcase-project/seedcase-theme/logos/sdca-logo.png differ diff --git a/_extensions/seedcase-project/seedcase-theme/logos/seedcase-logo.svg b/_extensions/seedcase-project/seedcase-theme/logos/seedcase-logo.svg new file mode 100644 index 0000000..fa02c65 --- /dev/null +++ b/_extensions/seedcase-project/seedcase-theme/logos/seedcase-logo.svg @@ -0,0 +1,6 @@ + + + + + + diff --git a/_extensions/seedcase-project/seedcase-theme/logos/sprout-logo.svg b/_extensions/seedcase-project/seedcase-theme/logos/sprout-logo.svg new file mode 100644 index 0000000..fe5edf2 --- /dev/null +++ b/_extensions/seedcase-project/seedcase-theme/logos/sprout-logo.svg @@ -0,0 +1,6 @@ + + + + + + diff --git a/_extensions/seedcase-project/seedcase-theme/site.webmanifest b/_extensions/seedcase-project/seedcase-theme/site.webmanifest new file mode 100644 index 0000000..45dc8a2 --- /dev/null +++ b/_extensions/seedcase-project/seedcase-theme/site.webmanifest @@ -0,0 +1 @@ +{"name":"","short_name":"","icons":[{"src":"/android-chrome-192x192.png","sizes":"192x192","type":"image/png"},{"src":"/android-chrome-512x512.png","sizes":"512x512","type":"image/png"}],"theme_color":"#ffffff","background_color":"#ffffff","display":"standalone"} \ No newline at end of file diff --git a/_extensions/seedcase-project/seedcase-theme/theme.scss b/_extensions/seedcase-project/seedcase-theme/theme.scss index b196bd8..82746b5 100644 --- a/_extensions/seedcase-project/seedcase-theme/theme.scss +++ b/_extensions/seedcase-project/seedcase-theme/theme.scss @@ -1,15 +1,26 @@ /*-- scss:defaults --*/ -@import url('https://fonts.googleapis.com/css2?family=Poppins'); -@import url('https://fonts.googleapis.com/css2?family=Lato'); +@import url('https://fonts.googleapis.com/css2?family=Noto Sans'); @import url('https://fonts.googleapis.com/css2?family=Fira+Code'); +@import url('https://fonts.googleapis.com/css2?family=Maven+Pro'); -$font-family-sans-serif: "Lato", sans-serif; +$font-family-sans-serif: "Maven Pro", sans-serif; $font-family-monospace: "Fira Code", monospace; -$headings-font-family: "Poppins", sans-serif; -$navbar-bg: #990032; +$headings-font-family: "Noto Sans", sans-serif; + +/* brand colour #003224 - the one below is a slightly lighter version of the brand colour */ +/* using rgb to be able to use rgba, i.e., opacity */ +$primary: rgb(25, 100, 64); // #196440 +$secondary: rgb(198, 240, 211); // #c6f0d3 +$tertiary: rgb(72, 220, 118); // #48dc76 +$toc-active-border: rgb(139, 139, 139); // #8b8b8b; + +$navbar-padding-y: .2rem; /*-- scss:rules --*/ +.navbar { + border-bottom: rgba($toc-active-border, 0.3) 1px solid; +} svg { display: block; @@ -18,3 +29,61 @@ svg { height: auto !important; width: auto !important; } + +li { + margin: 5px 0; +} + +figcaption { + text-align: center; +} + +.about-link { + background-color: $secondary !important; + border: 1px solid $tertiary !important; + border-radius: 50px !important; + color: $primary !important; +} + +.about-link:hover { + background-color: rgba($secondary, 0.3) !important; +} + +.about-links { + justify-content: left !important; + padding: 10px 0px 0px 0px !important; +} + +/* TODO: take inspiration from Quarto-web to make this cleaner */ +.landing-page-banner { + background-color: rgba($secondary, 0.3); + padding: 10px; + position: relative; + left: 50%; + right: 50%; + width: 100vw; + margin-left: -50vw; + margin-right: -50vw; +} + +.landing-page-banner-content { + max-width: 800px; + margin: 0 auto; + box-sizing: border-box; + margin-bottom: 40px; +} + +.card { + border-radius: 12px; + box-shadow: 0px 2px 4px rgba(0, 0, 0, 0.15); + background-color: rgba($secondary, 0.3); + border: none; + padding: 5px 20px 10px 20px; + margin-bottom: 40px; + height: 500px; + justify-content: start !important; +} + +.navbar-logo { + max-height: 38px; +} diff --git a/_quarto.yml b/_quarto.yml index 7f7706a..d0c7d4a 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -14,6 +14,8 @@ website: - text: "Contributing" href: "https://community.seedcase-project.org/" navbar: + title: false + logo: _extensions/seedcase-project/seedcase-theme/logos/navbar-logo-seedcase-decisions.svg pinned: true search: true tools: diff --git a/_template.qmd b/_template.qmd index 899e475..a7b255d 100644 --- a/_template.qmd +++ b/_template.qmd @@ -1,30 +1,30 @@ --- title: "" description: "Our reasons for ..." -author: "" -date: last-modified +date: "" categories: --- ::: content-hidden Use other decision posts as inspiration to writing these. +Leave the content-hidden sections in the text for future reference. ::: -## Context and Problem Statement +## Context and problem statement ::: content-hidden State the context and some background on the issue, then write a statement in the form of a question for the problem. ::: -## Decision Drivers +## Decision drivers ::: content-hidden List some reasons for why we need to make this decision and what things have arisen that impact work. ::: -## Considered Options +## Considered options ::: content-hidden List and describe some of the options, as well as some of the benefits and @@ -46,7 +46,7 @@ drawbacks for each option. ::: ::: -## Decision Outcome +## Decision outcome ::: content-hidden What decision was made, use the form "We decided on CHOICE because of diff --git a/_why-REST.qmd b/_why-REST.qmd new file mode 100644 index 0000000..235507f --- /dev/null +++ b/_why-REST.qmd @@ -0,0 +1,154 @@ +--- +title: "Why RESTful API" +description: | + REST is a widely used design style for developing APIs. +date: "2023-03-22" +draft: true +categories: + - api + - software-architecture +--- + + + +::: content-hidden +Use other decision posts as inspiration to writing these. Leave the +content-hidden sections in the text for future reference. +::: + +## Context and Problem Statement + +::: content-hidden +State the context and some background on the issue, then write a +statement in the form of a question for the problem. +::: + +Application programming interfaces (APIs) are ways that applications +communicate to each other through a standard structure or design. It is +important for a project like Seedcase to chose an API format early on, +bearing in mind both what will work best for the application but also +which resources there are available within the team. The question the +becomes: + +> Which API technology will best serve the needs of the Seedcase +> project? + +## Decision Drivers + +::: content-hidden +List some reasons for why we need to make this decision and what things +have arisen that impact work. +::: + + + +## Considered Options + +::: content-hidden +List and describe some of the options, as well as some of the benefits +and drawbacks for each option. +::: + +There are several design styles available for building APIs, including +Representational State Transfer (REST), Simple Object Access Protocol +(SOAP), and GraphQL. We have looked at REST, SOAP, and GraphQL as +possible API tech for Seedcase. + +### REST + + + +::: columns +::: column +#### Benefits + +- Is lightweight and easy to implement, making it a popular choice for + web-based applications +- Uses a simple and intuitive set of HTTP methods, which makes it easy + for developers to understand and use +- Provides a clear separation of responsibilities between the client + and server components, making it easier to develop, test, and deploy + each component independently +- Follows a conceptually simple and traditional approach where the + client sends a request to the server, and the server responds with + the requested data +- Is often simpler to implement and offers better caching mechanisms. +- Has better tooling support and is more widely adopted +::: + +::: column +#### Drawbacks + + + +- Item 1 +::: +::: + +### SOAP + +[SOAP](https://www.w3.org/TR/soap12-part0/) is a widely used technology +for implementing web services. SOAP is based on the XML protocol and +supports a wide range of messaging formats, such as binary and MIME +types, making it quite flexible. + +::: columns +::: column +#### Benefits + +- Based on XML +- Supports a number of messaging formats making it flexible +::: + +::: column +#### Drawbacks + +- Complex to implement +- Requires additional metadata and processing overhead + - can result in slower performance and higher resource consumption +- Difficult to debug and test due to its complexity and lack of + visibility in the underlying communication logs +::: +::: + +### GraphQL + +[GraphQL](https://graphql.org) is an increasingly popular technology for +building web APIs. GraphQL allows for very fine-grained control over +what data is requested and given, so it offers the most flexibility. +GraphQL can be integrated with REST API, which is a useful feature +especially when handling large and/or complex requests. So if needed, we +could incorporate GraphQL into existing REST API. + +::: columns +::: column +#### Benefits + +- Control over what is transmitted i very detailed +- Flexible +- Can be integrated into REST API +::: + +::: column +#### Drawbacks + +- Complex to set up and maintain +::: +::: + +## Decision Outcome + +::: content-hidden +What decision was made, use the form "We decided on CHOICE because of +REASONS." +::: + +We believe that the simplicity, flexibility, and scalability of REST +make it a better choice for the client-server communication needs of +Seedcase framework. + +### Consequences + +::: content-hidden +List some potential consequences of this decision. +::: diff --git a/_why-cyclical-workflow.qmd b/_why-cyclical-workflow.qmd index 3c8788f..78691f8 100644 --- a/_why-cyclical-workflow.qmd +++ b/_why-cyclical-workflow.qmd @@ -1,8 +1,7 @@ --- -title: "Why Cyclical Workflow" +title: "Why cyclical workflow" description: "" -author: "Luke W. Johnston" -date: last-modified +date: "" draft: true # categories: # - @@ -10,6 +9,7 @@ draft: true Follow the tidyverse team approach to repo development, by dedicating periods of time to specific repos, and rotating between. + ::: content-hidden Use other decision posts as inspiration to writing these. @@ -62,4 +62,4 @@ REASONS." ::: content-hidden List some potential consequences of this decision. -::: +::: \ No newline at end of file diff --git a/_why-github.qmd b/_why-github.qmd index 12b592d..0b14f12 100644 --- a/_why-github.qmd +++ b/_why-github.qmd @@ -8,32 +8,50 @@ draft: true --- # Why use Github? + + ::: content-hidden Use other decision posts as inspiration to writing these. ::: -## Context and Problem Statement +## Context and problem statement ::: content-hidden State the context and some background on the issue, then write a statement in the form of a question for the problem. ::: -## Decision Drivers + +## Decision drivers ::: content-hidden List some reasons for why we need to make this decision and what things have arisen that impact work. ::: -## Considered Options +## Considered options ::: content-hidden -List and describe some of the options, as well as some of the pros and -cons for each option. +List and describe some of the options, as well as some of the benefits and +drawbacks for each option. +::: + +### Option 1 + +::: {.columns} +::: {.column} +#### Benefits + +- Item 1 +::: +::: {.column} +#### Drawbacks + +- Item 1 +::: ::: -## Decision Outcome +## Decision outcome ::: content-hidden What decision was made, use the form "We decided on CHOICE because of diff --git a/_why-markdown.qmd b/_why-markdown.qmd new file mode 100644 index 0000000..e69de29 diff --git a/_why-text-based.qmd b/_why-text-based.qmd index 45e8974..66abd3e 100644 --- a/_why-text-based.qmd +++ b/_why-text-based.qmd @@ -1,8 +1,7 @@ --- title: "Why text/code-based tools?" description: "Our reasons for selecting tools that are based on code, rather than GUIs." -author: "Luke W. Johnston" -date: last-modified +date: "" draft: true categories: - documentation @@ -10,6 +9,8 @@ categories: - text --- + + "Everything as code" https://www.adaptavist.com/blog/everything-as-code-embracing-the-codified-evolution @@ -26,26 +27,25 @@ https://medium.com/geekculture/code-as-diagrams-whats-the-point-13dbe6053738 https://www.cloudbolt.io/blog/3-advantages-and-challenges-of-infrastructure-as-code-iac/ - ::: content-hidden Use other decision posts as inspiration to writing these. ::: -## Context and Problem Statement +## Context and problem statement ::: content-hidden State the context and some background on the issue, then write a statement in the form of a question for the problem. ::: -## Decision Drivers +## Decision drivers ::: content-hidden List some reasons for why we need to make this decision and what things have arisen that impact work. ::: -## Considered Options +## Considered options ::: content-hidden List and describe some of the options, as well as some of the benefits and @@ -67,7 +67,7 @@ drawbacks for each option. ::: ::: -## Decision Outcome +## Decision outcome ::: content-hidden What decision was made, use the form "We decided on CHOICE because of diff --git a/why-REST.qmd b/why-REST.qmd deleted file mode 100644 index ff6676e..0000000 --- a/why-REST.qmd +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: "Why RESTful API" -description: | - REST is a widely used design style for developing APIs. -author: "Richard Ding" -date: "2023-03-22" -date-modified: last-modified -draft: true -categories: - - api - - software-architecture ---- - - - -## Introduction - -Application programming interfaces (APIs) are ways that applications -communicate to each other through a standard structure or design. There -are several design styles available for building APIs, including Representational State Transfer (REST), Simple Object Access Protocol (SOAP), and GraphQL. - -## Decision - -We will use the REST architectural style for implementing the communication -protocol between our client and server components, instead of SOAP or -GraphQL. - -## Alternatives - -### SOAP - -[SOAP](https://www.w3.org/TR/soap12-part0/) is a widely used technology for implementing web services. SOAP is -based on the XML protocol and supports a wide range of messaging -formats, such as binary and MIME types, making it quite flexible. - -However, SOAP is fairly complex and heavyweight, which can make it more -difficult to implement and maintain. SOAP requires a lot of additional -metadata and processing overhead, which can result in slower performance -and higher resource consumption. SOAP can also be difficult to debug and -test due to its complexity and lack of visibility in the underlying -communication logs. - -### GraphQL - -[GraphQL](https://graphql.org) is an increasingly popular technology for building web APIs. -GraphQL allows for very fine-grained control over what data is requested -and given, so it offers the most flexibility. However, GraphQL can be -complex to set up and maintain, especially for simple use cases. GraphQL -can be integrated with REST API, which is a useful feature especially -when handling large and/or complex requests. So if needed, we could -incorporate GraphQL into existing REST API. - -## Reasons for the decision - -These are the reasons we are deciding on REST: - -- Is lightweight and easy to implement, making it a popular choice for - web-based applications. -- Uses a simple and intuitive set of HTTP methods, which makes it easy - for developers to understand and use. -- Provides a clear separation of responsibilities between the client - and server components, making it easier to develop, test, and deploy - each component independently. -- Follows a conceptually simple and traditional approach where the - client sends a request to the server, and the server responds with - the requested data. -- Is often simpler to implement and offers better caching mechanisms. -- Has better tooling support and is more widely adopted. - -## Conclusion -We believe that the simplicity, flexibility, and scalability of REST -make it a better choice for the client-server communication needs of Seedcase. \ No newline at end of file diff --git a/why-containers.qmd b/why-containers.qmd index 38d9085..b2b0519 100644 --- a/why-containers.qmd +++ b/why-containers.qmd @@ -3,9 +3,7 @@ title: "Why Containerization" description: | Containers are a way to bundle a software's environment to simplify development, installation, and dependency management. -author: "Richard Ding" date: "2022-12-10" -date-modified: last-modified categories: - containers - installation @@ -17,7 +15,7 @@ categories: -## What is Containerization +## What is containerization Containerization is the technology of packaging software development code along with all of its necessary dependencies or configurations, @@ -30,9 +28,9 @@ bubble around the software or application, keeping it apart from the actual computing environment. It eases moving or deploying the software or application to a new computing environment. -## Benefit of Containerization +## Benefit of containerization -### Lightweight/Portable +### Lightweight/portable Containers are "lightweight", since they can share the operating system kernel of the host computing environment. Containers also do not require @@ -70,13 +68,13 @@ automatically shut down, when it is no longer required. This method is called *orchestration*. The process of organising, controlling, scaling, and deleting containers can be achieved very easily. -### Ease of Management +### Ease of management Containers all run independently, so if one fails, the others will continue to run. Development teams gain the ability to fix errors in one container without affecting others. -### Developer-Friendly +### Developer-friendly Containers are developer-friendly, because they allow developers to use a single environment for development and production, which is a common diff --git a/why-conventional-branches.qmd b/why-conventional-branches.qmd new file mode 100644 index 0000000..f4727d2 --- /dev/null +++ b/why-conventional-branches.qmd @@ -0,0 +1,256 @@ +--- +title: "Conventional branches" +description: "Our reasons for using conventional branch names." +date: "2024-06-08" +categories: +- git +- branches +- communication +- collaboration +- teamwork +- workflow +--- + +::: content-hidden +Use other decision posts as inspiration to writing these. Leave the +content-hidden sections in the text for future reference. +::: + +## Context and problem statement + +::: content-hidden +State the context and some background on the issue, then write a +statement in the form of a question for the problem. +::: + +For the Seedcase Project, we aim to follow best practices and have +explicit and clear structures for how we work together. This includes +workflows on how we work with Git and GitHub (see the decision posts +[Why GitHub flow](why-github-flow.qmd), [Why atomic commits and +PRs](why-atomic-commits-and-prs.qmd), and [Why conventional +commits](why-conventional-commits.qmd)). + +Since we follow the GitHub flow, we need a structure for how we name our +branches, since branch naming is important for keeping a project +organised and understandable. As with commits, Git imposes very few +restrictions and it is up to the team to incorporate and follow a clear +structure. + +The question is: + +> Which naming scheme should we follow for branch naming to ensure clear +> and streamlined contributions? + +## Decision drivers + +::: content-hidden +List some reasons for why we need to make this decision and what things +have arisen that impact work. +::: + +In the collaborative and open-source environment of the Seedcase +Project, we wish to streamline how we name Git branches. If everyone +follows the same structure for naming branches, it will become easy to +identify and understand what work has been implemented in a branch. + +We want to provide a naming scheme for naming branches that: + +1. Is simple + +2. Is descriptive and informative, so it's easy for reviewers to + understand what work is being done on the branch + +3. Is easy to implement, for example with a VS Code extension + +4. Works well with the other workflow conventions we follow + +## Considered options + +::: content-hidden +List and describe some of the options, as well as some of the benefits +and drawbacks for each option. +::: + +When researching for branch naming conventions, most of the described +best practices involve a naming scheme that follows a structure similar +to Conventional Commits, which works very well for the Seedcase core +team, since we follow this convention for our commit messages (see the +[Why conventional commits](why-conventional-commits.qmd) decision post +for why we follow this convention). + +In general, these naming schemes involves a prefix describing the +**type** of branch and a short **description**. + +Like with Conventional Commits, the type prefix enables you to quickly +identify the purpose of the branch. Prefixes include `feat`, `fix`, +`docs`, and so on, following the conventional commits convention. + +In general, the following best practices apply for branch naming: + +1. Only use lower casing + +2. Only use alphanumeric characters (don't use punctuation, spaces, + underscores, or other any non-alphanumeric characters than hyphen) + +3. Use kebab-casing, i.e., separate words by hyphens (for example + `short-description-of-branch`) + +4. Concise and informative descriptions (avoid branch names longer than + 50 characters) + +There are, however, minor diverging conventions. The details of these +will be fleshed out below. + +### Include ticket/issue number + +When especially larger teams work on a project, they tend to have some +kind of project management system, with tickets or items for each +developer to work on. The Seedcase core team uses GitHub projects (see +the [Why GitHub projects](why-github-projects.qmd) post), which includes +numbering of issues across repositories. + +This information can easily be added to a branch name like so: + +``` +feat/issue-123-short-description +``` + +::: columns +::: column +#### Benefits + +- Clear reference that couples the issue and branch +::: + +::: column +#### Drawbacks + +- The branch name becomes longer + +- Risk of using incorrect issue numbers (due to mistyping or + misremembering) + +- Need for looking up the ticket number in the project management + system (GitHub for the Seedcase core team) + +- If only the issue ID is included, there is no explicit context for + your collaborators to know what the works of the branch covers. + Instead, reviewers may need to find the issue in the project + management system to figure out the context. +::: +::: + +### Use forward slash as separator between the type prefix and description + +It's common practice to use a forward slash (`/` ) between the prefix +and the description of a branch. Let's sum up the benefits and drawbacks +of this practice: + +::: columns +::: column +#### Benefits + +- Adds a clear separation of the prefix and description +- Shows a hierarchy in the branch name which many platforms and IDEs + (like VS Code) will recognise and sort branches by +::: + +::: column +#### Drawbacks + +- Could be confused with a directory structure +- Adds complexity to the branch name which could lead to errors and, + thus, inconsistencies +::: +::: + +### Include user ID or username + +Some teams include the initials of the author in the branch name to keep +track of each developer's work. + +::: columns +::: column +#### Benefits + +- Easy to track who is working on what +- Can be useful for larger teams +::: + +::: column +#### Drawbacks + +- Adds complexity to the branch name +- Could be seen as unnecessary, especially in smaller teams +::: +::: + +## Decision outcome + +::: content-hidden +What decision was made, use the form "We decided on CHOICE because of +REASONS." +::: + +We decided to follow the following naming scheme: + +``` +/short-description +``` + +This naming scheme is simple, descriptive, and informative, with a +structure that mimic the Conventional Commits convention which we follow +for commit messages. + +We decided to not include the issue number in the branch name, as it can +be seen as unnecessary and could lead to errors and inconsistencies. +Instead, we encourage developers to refer to the issue in the pull +request description. + +Since our team is small and we work closely together, we decided to not +include user IDs or usernames in the branch names to keep the complexity +of the branch names to a minimum. + +This convention is easy to implement, using the [Conventional +Branch](https://marketplace.visualstudio.com/items?itemName=pshaddel.conventional-branch) +extension for VS Code. This extension lets us define the wanted naming +structure and can easily be used to create new branches with the correct +naming convention (using the command palette in VS Code). + +By following this naming scheme, we ensure that all branches are named +in a consistent and clear way, making it easy for reviewers to +understand what work is being done on a branch. This will help +streamline the contribution process and make it easier for developers to +collaborate on the project. + +### Consequences + +::: content-hidden +List some potential consequences of this decision. +::: + +By not including issue number in the branch name, we need to make sure +that the issue is referenced in the pull request description. This can +be seen as an extra step, but it also ensures that the issue is properly +linked to the branch and the work done in the branch. + +If our core team grows, we might consider the inclusion of user IDs or +usernames in the branch names to keep track of each developer's work. +But for now, we decided to omit this to keep the naming scheme as simple +as possible. + +## Resources used for this post + +- [Best practices for naming Git + branches](https://graphite.dev/guides/git-branch-naming-conventions) +- [Naming conventions for Git Branches - a + Cheatsheet](https://medium.com/@abhay.pixolo/naming-conventions-for-git-branches-a-cheatsheet-8549feca2534) +- [A Simplified Convention for Naming Branches and Commits in + Git](https://dev.to/varbsan/a-simplified-convention-for-naming-branches-and-commits-in-git-il4) +- [Git Branching Naming Convention: Best Practices to + Follow](https://phoenixnap.com/kb/git-branch-name-convention) +- [Best Practices for Naming Git + Branches](https://tilburgsciencehub.com/topics/automation/version-control/advanced-git/naming-git-branches/) +- [🌿 The Ultimate Guide to Naming Git Branches: Best Practices and + Tips + 🔖](https://hardikchotaliya.hashnode.dev/the-ultimate-guide-to-naming-git-branches-best-practices-and-tips) diff --git a/why-conventional-commits.qmd b/why-conventional-commits.qmd new file mode 100644 index 0000000..eca0093 --- /dev/null +++ b/why-conventional-commits.qmd @@ -0,0 +1,255 @@ +--- +title: "Why conventional commits (with optional emojis)" +description: "Our reasons for using conventional commits (with optional emojis following the Gitmoji convention) across Seedcase repositories." +date: "2024-05-14" +categories: +- git +- commit messages +- communication +- collaboration +- teamwork +- workflow +--- + +::: content-hidden +Use other decision posts as inspiration to writing these. Leave the +content-hidden sections in the text for future reference. +::: + +## Context and problem statement + +::: content-hidden +State the context and some background on the issue, then write a +statement in the form of a question for the problem. +::: + +There are many ways to write commit messages, but having a consistent +and standardised convention to follow can streamline the project history +and make it easier to keep track of changes, as well as improve the +speed and efficacy of the review process. It can also support coherence +and consistency across contributions, which is especially important when +working in a team-based and open source setting. + +::: callout-caution +Note that the benefits described above are tightly coupled to a clear, +consistent workflow on commit frequency and content (see the decision +post on why we aim to make [atomic commits and +PRs](why-atomic-commits.qmd)). +::: + +Since commit message conventions are not enforced by Git itself, but +rather by the team working on a given project, the question becomes: + +> Which commit message convention should we follow when we write commit +> messages in Seedcase codebases? + +## Decision drivers + +::: content-hidden +List some reasons for why we need to make this decision and what things +have arisen that impact work. +::: + +In the Seedcase Project, we emphasise the open-source philosophies of +transparency and collaboration. Therefore, it is essential to have a +clear and consistent commit message convention to maintain these +principles, both within the team and across external contributions. + +Since we follow the [GitHub flow](why-github-flow.qmd), changes are made +on topic branches and reviewed before merging into the main branch. +Having a clear commit message convention can ease the review process, as +the context and purpose of changes will be clearer for reviewers. + +In addition, some commit message conventions can automate changelogs and +release processes, which is beneficial for version management and for +communicating changes to users and contributors. + +::: callout-caution +Note that most commit conventions and best practices follow the same +general principles, with some differences in syntax and structure. + +In general, a commit message should be **clear and concise** (brief, but +specific descriptions, avoiding vagueness and ambiguity), **relevant** +(focus the *why*, not the *how* of the implementation), and +**consistent** (follow a standard format). + +A commit message should: + +- Include a short descriptive title, potentially followed by a body + with more details. +- Use the imperative, present tense in the title and the body (e.g., + "Add feature" instead of "Added feature") +- Use the title to summarise the changes made in the commit. +- Use a potential body to provide context and justifications for the + change (such as elaboration on the changes, breaking changes, + reference of issues, and tagging relevant people). +::: + +## Considered options + +::: content-hidden +List and describe some of the options, as well as some of the benefits +and drawbacks for each option. +::: + +There seem to be many general recommendations for best practices and +fewer established conventions for how commit messages should be written. +We will consider the conventions Conventional Commits and Gitmoji in the +following sections. + +### Conventional commits + +The [Conventional Commits](https://www.conventionalcommits.org/) +convention builds on the [Angular +convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines), +but was generalised to go beyond Typescript. It's widely adopted due to +its compatibility with semantic versioning and automated release +processes. Moreover, it's commonly used in various software development +communities, including the open source communities. Its structured +format aligns well with the organized and systematic approach favoured +in open-source projects. It is also compatible with automated release +processes which makes it appealing for managing versioning in software +projects. + +In this way, the Conventional Commits convention adds a both human and +machine-readable structure to commit messages, which can help to make +the history of the project more understandable and easier to track. + +A conventional commit includes a **header**, an optional **body**, and +an optional **footer** in each commit message, like shown below: + +``` +[optional scope]: + +[optional body] + +[optional footer(s)] +``` + +The header includes a **type**, an optional **scope**, and a +**description** of the change. The **type** is a mandatory field that +specifies the kind of change that the commit is providing (like `feat`, +`fix`, `refactor`, `doc`, and `chore`). The **scope** is an optional +field that specifies the part of the codebase that the commit is +affecting. The **description** is a mandatory field that provides a +concise summary of the change. + +The optional **body** provides a longer description of the change, +including the motivation of why the changes was implemented and how it +contrasts with previous implementations. The optional **footer** +contains metadata about the change, such as potential breaking changes +and references to relevant issues. + +The conventional commits convention is also supported by a [VS Code +extension](https://marketplace.visualstudio.com/items?itemName=vivaxy.vscode-conventional-commits) +that eases the process of writing commit messages in the correct format. + +::: columns +::: column +#### Benefits + +- Provides a clear structure for commit messages. +- Has an easy-to-use VS Code extension. +- Can be used to generate changelogs. +- Widespread adoption in various software development and open-source + communities. +::: + +::: column +#### Drawbacks + +- It might be too verbose for some projects (but using the VS Code + extension eases the process substantially). +- No use of emojis which can make commit messages more visually + appealing and easier to scan for intention and purpose. +::: +::: + +### The Gitmoji convention + +The [Gitmoji](https://gitmoji.dev/) commit message convention +incorporates emojis to categorise commit messages. It's an initiative to +standardise the use of emojis in GitHub commit messages and it offers +explanations of the meaning of each emoji. Each commit message consists +of an **intention** (an emoji), an optional **scope**, and a +**message**, like shown below: + +``` +(): +``` + +Examples of intentions include `:sparkles:` for new features, `:bug:` +for bug fixes, `:recycle:` for refactoring, and `:memo:` for +documentation changes. The use of emojis can make commit messages more +visually appealing and easier to scan, especially for those who are more +visually oriented. + +::: columns +::: column +#### Benefits + +- Provides a clear structure for commit messages. +- Has an easy-to-use VS Code extension. +- The use of emojis can make commit messages more visually appealing + and easier to scan to identify the purpose or intention. +- Gitmoji is an open-source project which fits well with the + open-source philosophy of the Seedcase Project. +::: + +::: column +#### Drawbacks + +- For those not familiar with emojis or who are less visually + oriented, it might be harder to understand the meaning of the + commit. +- No structured format for the body or footer of the commit message to + provide more context. +::: +::: + +## Decision outcome + +::: content-hidden +What decision was made, use the form "We decided on CHOICE because of +REASONS." +::: + +When deciding which commit message convention to follow in all Seedcase +projects, the most important thing is to explicitly include a convention +that everyone agrees on and follows. Both conventions described above +include a structured format for commit messages, which can help to make +the history of the project more understandable and easier to track. + +We decided to use the **Conventional Commits** convention with the +inclusion of optional emojis (following the use of emojis in the +**Gitmoji** convention). The Conventional Commits convention is widely +adopted, has an easy-to-use [VS Code +extension](https://marketplace.visualstudio.com/items?itemName=vivaxy.vscode-conventional-commits), +and can be used to generate SemVar changelogs. Since emojis are +incorporated in the Conventional Commits extension, we have the option +to include emojis in commit messages to make commit messages more +visually appealing and easier to scan for purpose or intention. + +### Consequences + +::: content-hidden +List some potential consequences of this decision. +::: + +By using the Conventional Commits convention with optional emojis, we +aim to make our commit messages more consistent, informative, and +visually appealing. This will help to improve the readability of the +commit history, facilitate the review process, and automate changelogs +and release processes. This fits well with the open source philosophies +we strive to follow. However, to achieve these benefits, it is important +that everyone in the team as well as potential external contributors are +aware of and follow this convention. Within the Seedcase core team, we +all use VS Code and the easy-to-use extension enables us to follow the +Conventional Commits convention effortlessly. + +Note that following a commit message convention alone doesn't ensure a +clear project history. Following a commit convention that includes +commit content and frequency is as essential as a commit message +convention. See the [Why atomic commits and +PRs](why-atomic-commits-and-prs.qmd) decision post for a discussion of +such conventions. diff --git a/why-discord.qmd b/why-discord.qmd index fdeece3..5dd4752 100644 --- a/why-discord.qmd +++ b/why-discord.qmd @@ -1,68 +1,134 @@ --- title: "Why Discord" description: "Our reasons for using Discord as our communication platform." -author: "Luke W. Johnston" -date: last-modified +date: "2023-06-25" categories: - communication --- - +::: content-hidden +Use other decision posts as inspiration to writing these. +::: + +## Context and problem statement + +::: content-hidden +State the context and some background on the issue, then write a +statement in the form of a question for the problem. +::: Communication within a team is often done with email or, in more modern -and tech environments, with Slack. While email is a great tool when -communicating with people external to a team (or organization), there -are numerous reasons why it is a poor communication tool within teams -(and potentially across organizations). Without making this post about -why to *not* use email, a few reasons include: - -- It is asynchronous communication, so you can't chat in real-time, - which makes it not suited for team communication. -- Slow to write and send emails within a team (steps are: create new - email, type out all team members, write a subject, write an email - body, click send). -- Lack of history (without having to use the Search functionality all - the time, if emails are kept) of all dialogue within a team. -- New team members don't have access to history of dialogue within a - team. -- Organization of emails is dependent on the team member and not in - control of the team. You can't control how the information is stored - (related to the history). - -Email is a useful tool for certain types of communication, but it isn't -really the best option for team communication. Other tools like instant -messaging, project management software, or video conferencing are more -suitable for team collaboration and communication. - -Slack is a better option, since it has synchronous communication, and -you can control how information is distributed and organized (in -"Channels"). Their features are targeted to teams in corporate -environments, so the focus is more around productivity and work. -However, Slack's main focus is also, for us, its biggest weakness: It -isn't designed around being inclusive since corporate teams are by -default exclusive. Slack has also recently changed its pricing model, so -messages are not accessible after 90 days unless you pay (a high fee). - -An alternative to Slack is Discord, which has become a popular -communication platform, particularly for online communities. It was -originally built for use by people playing video games together in a -group, so they can chat while plying. However, because of this informal -and easy way of joining voice channels and the text channels, as well as -other features, non-gaming communities have been increasingly making use -of Discord because of its focus on community engagement. Here are -reasons why we are deciding to use it: - -- Its free plan is more suitable to our purposes. +and tech environments, with instant messengers like Slack. While email is a great tool +when communicating with people external to a team (or organization), +there are numerous reasons why it is a poor communication tool within +teams. It is therefore important to us to select a way of communicating +within our development team that will facilitate good cooperation. The +question here becomes: + +> Which tool should we use for inter-team communication? + +## Decision drivers + +::: content-hidden +List some reasons for why we need to make this decision and what things +have arisen that impact work. +::: + +With a geographically dispersed team it is important that we have a way +to 'talk' to each other in an information and quick way. Instant +messaging seems to be a good solution. There are quite a number of IMs +around, but we are looking at two that we believe would be suitable for +the Seedcase team. The first is Slack which is very popular in the +corporate world, and the second is Discord, which is slightly more +informal. We have not discarded emails, they are useful for some things, +but they are very cumbersome for quick questions and water-cooler chats. + +## Considered options + +::: content-hidden +List and describe some of the options, as well as some of the benefits +and drawbacks for each option. +::: + +### Slack + +Slack has synchronous communication, and you can control how information +is distributed and organized (in "Channels"). Their features are +targeted to teams in corporate environments, so the focus is more around +productivity and work. However, Slack's main focus is also, for us, its +biggest weakness: It isn't designed around being inclusive since +corporate teams are by default exclusive. Slack has a free version, the +main difference with the paid subscription is that messages are not +accessible after 90 days. + +::: columns +::: column +#### Benefits + +- Instant messaging with colleagues +- Option to create channels or groups for specific jobs or teams +- It is possible to download conversation in groups, as well as + personal chats to avoid knowledge loss +::: + +::: column +#### Drawbacks + +- History is lost after 90 days on the free version +- Traditionally not geared towards voice communication (although it + does support that) +- Only 1-on-1 conversations (Huddles) in the free version +::: +::: + +### Discord + +Discord has become a popular communication platform, particularly for +online communities. It was originally built for use by people playing +video games together in a group, so they can chat while plying. However, +because of this informal and easy way of joining voice channels and the +text channels, as well as other features, non-gaming communities have +been increasingly making use of Discord because of its focus on +community engagement. + +::: columns +::: column +#### Benefits + +- Free version with no restrictions on functionality +- You can video/voice call with individuals and teams and share + screens +- History is always available, and accessible to new members added to + groups +::: + +::: column +#### Drawbacks + +- Not entirely intuitive for beginners +- Adds for 'fun' add-ons must be closed every time you log in +- Historically a problem with uptime, but hovering around 99.6% for + the last couple of years +::: +::: + +## Decision outcome + +::: content-hidden +What decision was made, use the form "We decided on CHOICE because of +REASONS." +::: + +We have decided on Discord for the following reasons: + +- Its free plan is very suitable for our purposes - Its overall focus and values (community based) align with our goals and values, since we want to encourage and build an online (and in - person) community around Seedcase and related projects. + person) community around Seedcase and related projects - Text chat history is available in the free version. So onboarding a - new member is easier for them to see what's been happening. + new member is easier for them to see what's been happening - Joining the voice/video channels are very easy, which is perfect in - remote working settings and when co-working together. - -There are few other reasons, but these are the biggest ones why we -decided on using Discord. + remote working settings and when co-working together \ No newline at end of file diff --git a/why-django.qmd b/why-django.qmd index a905c15..4159aa5 100644 --- a/why-django.qmd +++ b/why-django.qmd @@ -1,11 +1,9 @@ --- title: "Why Django" description: | - Web frameworks are designed to support building a web frontend as well - as the API layer. Django is a popular and widely used framework. -author: "Richard Ding" + Web frameworks are designed to support building both web front ends and API layers. Django is a popular full-stack framework with solutions for most web development tasks out of the box. date: "2023-03-22" -date-modified: last-modified +date-modified: "2024-05-16" categories: - api - web @@ -13,102 +11,243 @@ categories: - software-architecture --- - - -## Introduction - -We have evaluated several web frameworks for the Seedcase Product, and -have chosen [Django](https://www.djangoproject.com) as the most suitable option for the web framework. -This document describes the reasoning behind this decision and outlines -the key factors that influenced it. - -## Decision - -After evaluating Flask, Ruby on Rails, FastAPI, and Django, we have -decided to use Django as the web framework for Seedcase. - -All considered web frameworks use Python. For our decision to use Python, see the page [Why Python](why-python.qmd). - -## Alternatives Considered +::: content-hidden +Use other decision posts as inspiration to writing these. Leave the +content-hidden sections in the text for future reference. +::: + +## Context and problem statement + +::: content-hidden +State the context and some background on the issue, then write a +statement in the form of a question for the problem. +::: + +Web applications all have a host of common functionalities (e.g. HTTP +request handling, URL routing, or data source integration). These can +take significant time and effort to implement from scratch and maintain +for each new project. Good frameworks provide mature, well-maintained +components for these features out of the box as well as best-practice +patterns and guidelines for structuring code consistently. They also +promote code reuse and modular design both within and between +applications. + +Overall, frameworks make applications robust, secure and scaleable, +collaborative development quicker and easier, and software maintenance +less onerous, allowing the team to focus on implementing +project-specific features. + +The question then becomes: + +> Which coding web framework will best suit our needs in developing +> Seedcase software? + +## Decision drivers + +::: content-hidden +List some reasons for why we need to make this decision and what things +have arisen that impact work. +::: + +We are developing Seedcase in Python (see [Why Python](why-python.qmd) +for more information about this decision), so we only consider web +frameworks for Python. The core part of Seedcase software is or will be +a relatively complex web application with a front end, an API and a data +layer, so we are looking for a full-stack framework that comes with +solutions for common tasks in all these layers. More particularly, we +are looking for tools that facilitate interactive web page design, form +handling, URL mapping, serialisation, REST API development, and database +management. As Seedcase software has users with differentiated roles and +privileges, a good user management system with support for +authentication and authorisation mechanisms is important. Working with +relational data, raw data files, and image files is a central concern, so +the framework should integrate well with popular databases and make it +easy to access the local file system. + +Additionally, the framework should be mature and well documented, with +an active community and extensive resources (e.g. tutorials, forum +posts, GitHub issues). + +Finally, we don't expect an above-average request throughput nor are we +a real-time data source to external systems, so performance is not the +highest ranking factor. + +## Considered options + +::: content-hidden +List and describe some of the options, as well as some of the benefits +and drawbacks for each option. +::: + +### Django + +[Django](https://www.djangoproject.com) is a full-stack framework for +building server-rendered web applications following a +[Model-View-Template](https://www.geeksforgeeks.org/django-project-mvt-structure/) +pattern. + +::: columns +::: column +#### Benefits + +- Has excellent support for API development, including frameworks for + [REST](https://restfulapi.net/) and [GraphQL](https://graphql.org/) + architectures. +- With the [REST framework](https://www.django-rest-framework.org/), + Django offers built-in solutions for all common web development + tasks, such as HTTP request handling, serialisation, URL routing, + pagination, filtering and internationalisation. +- Comes with a wide range of tools for user management, such as user + profiles, mechanisms for account activation and password reset, and + a customisable authentication system with support for social + authentication. +- Promotes security best-practices through the built-in authentication + system, role-based access control, fine-grained permissions, + Cross-Site Request Forgery (CSRF) protection and password hashing. +- Provides a powerful Object-Relational Mapper (ORM) that abstracts + away much of the database logic and allows developers to work with + database models in a Pythonic way. +- Supports all major databases (including PostgreSQL - see our [Why + PostgreSQL](why-postgres.qmd) decision post) and has a migration + mechanism, making it easy to evolve the database schema over time. +- Has good file storage support, making it easier to work with raw + data and image files. +- Comes with an admin interface out of the box, allowing non-technical + users to manage the application's data. +- Offers built-in form handling capabilities with customisable form + classes and form validation logic. +- Uses server-side rendering by default, enabling fast webpage + renders. +- Has a template engine for creating dynamic HTML pages. +- Makes it easy to compose Django applications. +- Has a wide array of well-maintained packages. +- Has excellent documentation and a large and active developer + community. +::: + +::: column +#### Drawbacks + +- Has a steeper learning curve because of its extensive set of + features. +- May require more complex configuration and additional extensions to + offer the same level of support for asynchronous programming as the + default offered by FastAPI. +- More opinionated than other frameworks, with less flexibility about + the choice of project structure, ORM and template engine. +- Server-rendered websites can have slower response times, which can + limit interactivity. +- Using the built-in template engine creates a tighter coupling + between backend and front end, potentially complicating code reuse + and maintenance. +::: +::: ### Flask -[Flask](https://flask.palletsprojects.com/en/2.3.x/) is a lightweight web framework that is easy to use and has a low -learning curve. It provides a lot of flexibility and does not enforce -any particular project structure. Flask has a small footprint and is a -good option for simple web applications or prototypes. - -However, Flask does not provide some of the advanced features that -Django has, such as an admin interface, an object-relational mapper -(ORM), and a built-in authentication system. These features would need -to be implemented manually or by using third-party libraries. - -### Ruby on Rails - -[Ruby on Rails](https://rubyonrails.org) is a popular web framework that provides a lot of built-in -features and conventions. It has a large and active community and -provides good support for agile development practices. Ruby on Rails is -a good option for rapid application development and has good support for -testing. - -However, Ruby on Rails requires developers to have experience with the -Ruby programming language, which may not be ideal for all teams and -isn't a common language in scientific environments. Additionally, Ruby -on Rails has a large footprint and can be slow for certain use cases. +[Flask](https://flask.palletsprojects.com/en/3.0.x/) is a lightweight +web framework, designed to be simple and flexible. + +::: columns +::: column +#### Benefits + +- Has a gentler learning curve and might be easier to use compared to + other options. +- Provides a lot of flexibility without enforcing a particular project + structure, ORM or front-end solution. +- Has a smaller footprint, which may lead to a small performance gain. +- Has a default template engine. +- Good option for simple web applications or prototypes. +- Has an active community, good resources and a fair selection of + third-party extensions. +::: + +::: column +#### Drawbacks + +- Provides fewer features out of the box than Django. Authentication, + user management, serialisation, form handling, object-relational + mapping and the admin interface would need to be implemented from + scratch or added through community-maintained extensions. +- Developers have a more active role in responding to security + concerns and ensuring that security best practices are implemented + appropriately. +::: +::: ### FastAPI -[FastAPI](https://fastapi.tiangolo.com) is a modern, high-performance web framework for building APIs -with Python. It is designed to be fast, and easy to use. FastAPI -includes features like automatic validation of request bodies, async -support, and built-in OpenAPI documentation. These features make it a -popular choice for building scalable and maintainable APIs, especially -for applications that require high performance real-time responses. - -However, it's important to consider the specific needs of the -Seedcase Product. FastAPI may be a good choice for applications that require -high performance real-time responses, but not as good a choice for more -complex web applications that require a full-stack framework with many -built-in features. It is also newer, so it is still maturing and has a -small, though active, community, which limits the amount of available -support and resources. - -## Factors that influenced the decision - -Several factors influenced our decision to use Django over Flask, -FastAPI, and Ruby on Rails as the web framework: - -### API Development - -Django provides excellent support for API development through its -built-in serialization framework and REST framework. The REST framework -provides a lot of functionality out of the box, such as authentication, -pagination, and filtering. Additionally, Django provides good support -for other types of APIs, such as GraphQL. - -### Data Management - -Django provides a powerful ORM that abstracts away much of the database -logic and allows developers to work with database models in a Pythonic -way. It provides good support for migrations, which makes it easy to -evolve the database schema over time. Django also provides a built-in -admin interface that allows non-technical users to manage data. - -### Security - -Django provides good support for security through its built-in -authentication system and its support for common security practices such -as Cross-Site Request Forgery (CSRF) protection and password hashing. It also provides good support -for role-based access control and fine-grained permissions. - -### User Management - -Django provides good support for user management through its built-in -authentication system and its support for user profiles and social -authentication. It also provides good support for password resets and -account activation. - -## Conclusion - -After evaluating Flask, FastAPI, Ruby on Rails, and Django, we have made -the decision that Django is the better fit for Seedcase. Django has the benefits of a built-in serialization framework and REST framework for API development, providing a powerful ORM and good built-in support for security, as well as user management. \ No newline at end of file +[FastAPI](https://fastapi.tiangolo.com) is a modern web framework for +building APIs with a focus on speed and performance. It is particularly +well-suited for applications that need to handle a large volume of +requests in real time. + +::: columns +::: column +#### Benefits + +- Easier to use compared to some of the other options and requires + less setup. +- Offers exceptional performance thanks to its native support for + asynchronous programming. +- Has built-in request and query parameter validation. +- Comes with automatic OpenAPI schema generation and documentation + UIs. +::: + +::: column +#### Drawbacks + +- Has a narrow range of full-stack features out of the box, similar to + Flask. +- Has no built-in template engine. +- A newer, maturing project with more limited support and resources. +::: +::: + +## Decision outcome + +::: content-hidden +What decision was made, use the form "We decided on CHOICE because of +REASONS." +::: + +We decided on Django because the requirements of Seedcase software are a +closer match to what Django offers, so we are well-placed to take +advantage of many of its core features. Django's built-in ORM, extensive +user management capabilities, feature-rich REST framework, and solid +security principles will save us significant development time and effort +and help us create a reliable and long-lived product. The native +template engine is also attractive, in that it will allow us to iterate +over user interfaces quickly, without the overhead of maintaining a +separate front-end framework. + +While Flask and FastAPI offer more flexibility and autonomy, this is not +necessarily an unambiguous positive for us, because we would need to +make and justify more decisions about our choice of project structure +and third-party extensions. Moreover, the more extensions we rely on, +the greater the effort involved in vetting for security and managing +dependency updates. As Seedcase software products will likely not be +performance-critical applications, the performance gain offered by +FastAPI is not a particularly relevant factor. + +### Consequences + +::: content-hidden +List some potential consequences of this decision. +::: + +As we will be rendering our web pages on the server side, we should keep +an eye out for any user-experience issues in our interaction-heavy user +flows, like the data upload or the data project application process. We +may consider streamlining interactions on the client side using inline +JavaScript in our Django templates. + +A further point to keep in mind is that the integrated template-based +architecture may create a tighter coupling between the front end and the +API layer. While we don't have a specific need to decouple the frontend +more formally — as we will not have other user interfaces linked to the +API and external interacting systems are well-served by dedicated API +endpoints — tightly coupled components can become difficult to refactor +or reuse as application complexity grows. diff --git a/why-docker.qmd b/why-docker.qmd index 6420c89..d3f2dd5 100644 --- a/why-docker.qmd +++ b/why-docker.qmd @@ -3,9 +3,7 @@ title: "Why Docker" description: | While there are several container technologies, Docker is one of the most popular and commonly used technologies. -author: "Richard Ding" date: "2022-12-14" -date-modified: last-modified categories: - container - software @@ -24,7 +22,8 @@ are different platforms on the market, each with unique approaches and use cases. Even though all have a similar concept of images and containers, there are some technical differences worth noting. -As to why we have chosen containerization, see the page [Why choose containerization technology](why-containers.qmd). +As to why we have chosen containerization, see the page [Why choose +containerization technology](why-containers.qmd). ## Comparison of technologies @@ -33,9 +32,12 @@ As to why we have chosen containerization, see the page [Why choose containeriza Docker is without a doubt the most popular container application/platform. According to Stack Overflow's [2020 Developer Survey](https://insights.stackoverflow.com/survey/2020), which included -almost 65,000 respondents, Docker was the [third most popular](https://insights.stackoverflow.com/survey/2020#technology-platforms) platform -among developers, trailing only Linux and Windows. In this survey, Docker -was the [most wanted and the second most loved](https://insights.stackoverflow.com/survey/2020#technology-most-loved-dreaded-and-wanted-platforms) platform. +almost 65,000 respondents, Docker was the [third most +popular](https://insights.stackoverflow.com/survey/2020#technology-platforms) +platform among developers, trailing only Linux and Windows. In this +survey, Docker was the [most wanted and the second most +loved](https://insights.stackoverflow.com/survey/2020#technology-most-loved-dreaded-and-wanted-platforms) +platform. Docker is incredible in many ways. It is a developer-friendly open source platform that can be used for rapid application development and @@ -55,10 +57,11 @@ from the outside environment. ### Podman -[Podman](https://podman.io) is an open-source, Linux-native tool designed to develop, manage, -and run containers and pods under the Open Container Initiative (OCI) -standards. Presented as a user-friendly container orchestrator developed -by [Red Hat](https://www.redhat.com/en). +[Podman](https://podman.io) is an open-source, Linux-native tool +designed to develop, manage, and run containers and pods under the Open +Container Initiative (OCI) standards. Presented as a user-friendly +container orchestrator developed by [Red +Hat](https://www.redhat.com/en). Podman is a daemonless container engine that enables users to create, manage, and run OCI Containers on the Linux system. Podman, like Docker, @@ -74,11 +77,11 @@ containers is viewed by some as improving system security. ### rkt -[rkt](https://github.com/rkt/rkt), like other container technologies, lets you separate your software -from its surroundings. However, rkt provides adjustable isolation, -allowing you to choose the appropriate amount of isolation utilising -rkt's pluggable runtime architecture, which is divided into different -phases. +[rkt](https://github.com/rkt/rkt), like other container technologies, +lets you separate your software from its surroundings. However, rkt +provides adjustable isolation, allowing you to choose the appropriate +amount of isolation utilising rkt's pluggable runtime architecture, +which is divided into different phases. rkt also includes security measures like a signature verification by default and even privilege separation, which is in charge of retrieving @@ -88,7 +91,9 @@ unforeseen vulnerabilities. The rkt is not a complete platform, end-to-end solution. It is instead utilised in conjunction with other technologies or in substitute of -particular Docker system components. Furthermore, the [rkt project](https://github.com/rkt/rkt) has been archived on GitHub as of February, 2020. +particular Docker system components. Furthermore, the [rkt +project](https://github.com/rkt/rkt) has been archived on GitHub as of +February, 2020. ### Hyper-V @@ -109,13 +114,13 @@ as the host. ## Conclusion After researching the container platform on the market, Docker still is -the best option for Seedcase. First of all, Docker has the world's -largest repository of container images that allow Docker users to -create, test, store and distribute containers. Secondly, Docker is a +the best option for Seedcase software. First of all, Docker has the +world's largest repository of container images that allow Docker users +to create, test, store and distribute containers. Secondly, Docker is a single, robust, and autonomous tool. Docker manages, runs, builds, and does all other container-related tasks independently of any other third-party tools. Lastly, Docker has a lengthy history of working with -well-known cloud platforms like Amazon Web Services (AWS) and Google Cloud -Platform (GCP). It is also compatible with Microsoft, Azure, and OpenStack. -Overall, regardless of how great the alternatives are, Docker is the most -suitable container platform for this project. +well-known cloud platforms like Amazon Web Services (AWS) and Google +Cloud Platform (GCP). It is also compatible with Microsoft, Azure, and +OpenStack. Overall, regardless of how great the alternatives are, Docker +is the most suitable container platform for this project. diff --git a/why-fly.qmd b/why-fly.qmd index 1b0b6a0..1de69ce 100644 --- a/why-fly.qmd +++ b/why-fly.qmd @@ -3,7 +3,6 @@ title: "Why Fly.io" description: | Showcasing a demo of Seedcase software helps make things more tangible. This post describes our reasons for using Fly.io as a deployment host for showcasing our demo. -author: "Philip Christiansen" date: "2023-12-08" date-modified: last-modified categories: @@ -12,71 +11,126 @@ categories: - deployment --- -## Context and Problem Statement +## Context and problem statement -We need some way to test and visually see how Seedcase deploys and works "live". The best solution would be to use a cloud provider, so we can easily deploy and visualize the progress of Seedcase. +We need some way to test and visually see how Seedcase software deploys +and works "live". The best solution would be to use a cloud provider, so +we can easily deploy and visualize the progress of Seedcase products. -This is relevant for reviewing code changes and for manual and user-experience testing. Ideally, this environment should be similar to a future production environment, but this may vary a lot based on the team/organisation that will use Seedcase. +This is relevant for reviewing code changes and for manual and +user-experience testing. Ideally, this environment should be similar to +a future production environment, but this may vary a lot based on the +team/organisation that will use our software. So our question is: -> Which cloud hosting provider should we use for our demonstrating and testing purposes? +> Which cloud hosting provider should we use for our demonstrating and +> testing purposes? -## Decision Drivers +## Decision drivers We want to decide on a cloud provider based on these features/metrics: -- Price: Relatively inexpensive in costs, since it will only be for demonstration purposes. -- Easy of use: It shouldn't be too difficult to use. -- Customisable: The provider should be easy to customise to use different frameworks/tools, if we need to adjust. For instance we should be able to use either of: venv, poetry, docker and etc. -- GitHub Authentication: The cloud provider should integrate with GitHub Authentication, because we already use GitHub for the Seedcase repositories and project management. -- GitHub Actions Integration: The cloud provider should integrate with GitHub Actions, allowing us to create pipelines easily. -- Managed PostgreSQL: It should have a managed PostgreSQL database to store application data if needed. -- "Native" support for Django application: It should have support for running a Django application without the need to wrap it in package or Docker container. -- Docker image or Dockerfile support: The cloud provider should also have support for running Docker images. Potentially, providing a Dockerfile would be convenient. -- Docker-compose support: A cloud provider with docker-compose support would allow us to easily spin up complicated environment (application, database and etc) in a similar way as we do locally. -- Logging and alerting: Logging and alerts would be nice features for the cloud provider, but not so relevant (and, therefore, not required) for a demo environment. -- Similar to production environment: We want the demo environment to be similar to the production environment, but this may vary a lot based on the team/organisation using the software. - -## Considered Options - -We have considered five different cloud providers: [Azure](https://azure.microsoft.com/en-us), [Render](https://render.com/), [Digital Ocean](https://www.digitalocean.com/), [Vercel](https://vercel.com/) and [Fly.io](https://fly.io/) . Below you see a "decision matrix" based on the different features. - -| | Azure | Render | Digital Ocean | Vercel | Fly.io | -|--------------------------------------------------------------|-----------------|--------------------------------------|--------------------------|------------------------|-----------------------------| -| Price (per month) | 1000kr | Free or 19$ user + 20$ DB | ? | Free or 20$ user | Cost for usage only | -| Ease of use | Hard | Easy | Medium | Easy | Easy / Medium | -| Customizability (venv, Poetry, Docker) | High | Medium | High | Low | Medium | -| GitHub Authentication | No | Yes | Yes | Yes | Yes | -| GitHub Actions Integration | Very good | Sort of (deploy webhook) | Yes | Yes | Very good | -| Managed Postgres | Yes | Yes | Yes | Yes | Yes (sort of) | -| File Storage service | Yes | Yes (FTP) 0.25\$/GB | | | Yes (\$0.15 GB) | -| Native support for Django app | Sort of | Yes (Poetry support) | ? | Yes (requirements.txt) | No | -| Docker Image or Dockerfile support | Yes | Yes | Yes | No | Yes | -| Docker-compose | Yes | No (but has render.yml) | Yes (with a normal node) | No | No | -| Logging | Very good logs | Simple | Simple | Simple | Yes | -| Alerts | Yes | No | ? | No | ? | -| Similar to production environment (Aarhus University server) | Likely possible | Maybe if Docker on university server | Likely | No | Yes if docker | - -## Decision Outcome - -We have decided to utilise Fly.io for our demo and testing needs. Fly.io is very cheap and the cost is not based on the number of users - only the actual usage (around 1$). It integrates with GitHub and the deployment is easy to setup with a GitHub action. This part is less user-friendly than **Render** and **Vercel**, where the deployment happens automatically. However, we would eventually adjust this "magic deployment" anyway to do tests and etc. before deploying. - -Fly.io uses Docker images, so there is no "native" support for a Django application, but `flyctl` automatically creates a Dockerfile which makes it easy anyway. - -Fly.io automatically and relatively quickly scales up an app when needed, which makes it very cheap. Furthermore, Fly.io owns all the servers, which makes it cheap compared to other providers which are usually relying on AWS or Azure. - -Fly.io has a customisable metrics dashboard (every app has access to Prometheus and Grafana). +- Price: Relatively inexpensive in costs, since it will only be for + demonstration purposes. +- Easy of use: It shouldn't be too difficult to use. +- Customisable: The provider should be easy to customise to use + different frameworks/tools, if we need to adjust. For instance we + should be able to use either of: venv, poetry, docker and etc. +- GitHub Authentication: The cloud provider should integrate with + GitHub Authentication, because we already use GitHub for the + Seedcase repositories and project management. +- GitHub Actions Integration: The cloud provider should integrate with + GitHub Actions, allowing us to create pipelines easily. +- Managed PostgreSQL: It should have a managed PostgreSQL database to + store application data if needed. +- "Native" support for Django application: It should have support for + running a Django application without the need to wrap it in package + or Docker container. +- Docker image or Dockerfile support: The cloud provider should also + have support for running Docker images. Potentially, providing a + Dockerfile would be convenient. +- Docker-compose support: A cloud provider with docker-compose support + would allow us to easily spin up complicated environment + (application, database and etc) in a similar way as we do locally. +- Logging and alerting: Logging and alerts would be nice features for + the cloud provider, but not so relevant (and, therefore, not + required) for a demo environment. +- Similar to production environment: We want the demo environment to + be similar to the production environment, but this may vary a lot + based on the team/organisation using the software. + +## Considered options + +We have considered five different cloud providers: +[Azure](https://azure.microsoft.com/en-us), +[Render](https://render.com/), [Digital +Ocean](https://www.digitalocean.com/), [Vercel](https://vercel.com/) and +[Fly.io](https://fly.io/) . Below you see a "decision matrix" based on +the different features. + +| | Azure | Render | Digital Ocean | Vercel | Fly.io | +|----------------|------------|------------|------------|------------|------------| +| Price (per month) | 1000kr | Free or 19\$ user + 20\$ DB | ? | Free or 20\$ user | Cost for usage only | +| Ease of use | Hard | Easy | Medium | Easy | Easy / Medium | +| Customizability (venv, Poetry, Docker) | High | Medium | High | Low | Medium | +| GitHub Authentication | No | Yes | Yes | Yes | Yes | +| GitHub Actions Integration | Very good | Sort of (deploy webhook) | Yes | Yes | Very good | +| Managed Postgres | Yes | Yes | Yes | Yes | Yes (sort of) | +| File Storage service | Yes | Yes (FTP) 0.25\$/GB | | | Yes (\$0.15 GB) | +| Native support for Django app | Sort of | Yes (Poetry support) | ? | Yes (requirements.txt) | No | +| Docker Image or Dockerfile support | Yes | Yes | Yes | No | Yes | +| Docker-compose | Yes | No (but has render.yml) | Yes (with a normal node) | No | No | +| Logging | Very good logs | Simple | Simple | Simple | Yes | +| Alerts | Yes | No | ? | No | ? | +| Similar to production environment (Aarhus University server) | Likely possible | Maybe if Docker on university server | Likely | No | Yes if docker | + +## Decision outcome + +We have decided to utilise Fly.io for our demo and testing needs. Fly.io +is very cheap and the cost is not based on the number of users - only +the actual usage (around 1\$). It integrates with GitHub and the +deployment is easy to setup with a GitHub action. This part is less +user-friendly than **Render** and **Vercel**, where the deployment +happens automatically. However, we would eventually adjust this "magic +deployment" anyway to do tests and etc. before deploying. + +Fly.io uses Docker images, so there is no "native" support for a Django +application, but `flyctl` automatically creates a Dockerfile which makes +it easy anyway. + +Fly.io automatically and relatively quickly scales up an app when +needed, which makes it very cheap. Furthermore, Fly.io owns all the +servers, which makes it cheap compared to other providers which are +usually relying on AWS or Azure. + +Fly.io has a customisable metrics dashboard (every app has access to +Prometheus and Grafana). The other cloud providers, where not chosen for these reasons: -- Render was our initial choice. It was cheap and easy to setup, but the cost is per user plus the usage (around 100$ per month vs 1$ for Fly). Render is very user friendly with magic deployments, but we would need to adjust these anyway for test and etc. -- Azure is able to do everything we require, but it is too complicated for a demo environment. -- Vercel is easy to use, but lacks customisability. For instance, it seemed not to work so well with Poetry and it is unable to work with Docker. -- Digital Ocean could be a fair choice, but I was unable to make it work - so in that sense it fails the "ease of use"-criteria. +- Render was our initial choice. It was cheap and easy to setup, but + the cost is per user plus the usage (around 100\$ per month vs 1\$ + for Fly). Render is very user friendly with magic deployments, but + we would need to adjust these anyway for test and etc. +- Azure is able to do everything we require, but it is too complicated + for a demo environment. +- Vercel is easy to use, but lacks customisability. For instance, it + seemed not to work so well with Poetry and it is unable to work with + Docker. +- Digital Ocean could be a fair choice, but I was unable to make it + work - so in that sense it fails the "ease of use"-criteria. ### Consequences -- PostgreSQL is a natural part of Fly.io, but it is not a **Managed PostgreSQL** like the other cloud providers. A PostgreSQL is "just an app" in Fly.io, so it might require a bit more maintenance. However, even in the unlikely scenario of complete data loss, there is no significant impact since Fly.io serves solely as a demonstration environment. -- Storage is cheap in Fly.io, but there are some limitations [Volume considerations](https://fly.io/docs/reference/volumes/#volume-considerations). But again this is only a demo environment -- Fly.io lacks docker-compose support, so we will not be able to reuse docker-compose files from our local development. +- PostgreSQL is a natural part of Fly.io, but it is not a **Managed + PostgreSQL** like the other cloud providers. A PostgreSQL is "just + an app" in Fly.io, so it might require a bit more maintenance. + However, even in the unlikely scenario of complete data loss, there + is no significant impact since Fly.io serves solely as a + demonstration environment. +- Storage is cheap in Fly.io, but there are some limitations [Volume + considerations](https://fly.io/docs/reference/volumes/#volume-considerations). + But again this is only a demo environment +- Fly.io lacks docker-compose support, so we will not be able to reuse + docker-compose files from our local development. diff --git a/why-github-flow.qmd b/why-github-flow.qmd index c2fc848..a993723 100644 --- a/why-github-flow.qmd +++ b/why-github-flow.qmd @@ -1,8 +1,7 @@ --- -title: "Why GitHub Flow" -description: "Our reasons for using the GitHub Flow as our branching and development strategy." -author: "Signe Kirk Brødbæk" -date: last-modified +title: "Why GitHub flow" +description: "Our reasons for using the GitHub flow as our branching and development strategy." +date: "2024-02-15" categories: - decision - workflow @@ -64,7 +63,7 @@ references: year: n.d. URL: https://githubflow.github.io - id: githubflow - title: GitHub flow - Follow GitHub flow to collaborateon projects. + title: GitHub flow - Follow GitHub flow to collaborate on projects. author: family: GitHub issued: @@ -79,123 +78,198 @@ nocite: | Use other decision posts as inspiration to writing these. ::: -## Context and Problem Statement +## Context and problem statement ::: content-hidden State the context and some background on the issue, then write a statement in the form of a question for the problem. ::: -Since we develop software in a collaborative setting, we believe it's important to implement an explicitly stated Git branching strategy. This aligns with our [Guiding Principles](https://seedcase-project.org/principles). A clear and well-defined branching strategy enables consistency and efficiency, and, as a result, cleaner workflows across contributions with more time to focus on actual collaboration, problem-solving, and ensuring high quality work. +Since we develop software in a collaborative setting, we believe it's +important to implement an explicitly stated Git branching strategy. This +aligns with our [Guiding +Principles](https://seedcase-project.org/principles). A clear and +well-defined branching strategy enables consistency and efficiency, and, +as a result, cleaner workflows across contributions with more time to +focus on actual collaboration, problem-solving, and ensuring high +quality work. -There are several branching strategies available, each with its own set of advantages and disadvantages. Which strategy is the most suitable depends on the project, the team, and the organisation (as well as preferences). +There are several branching strategies available, each with its own set +of advantages and disadvantages. Which strategy is the most suitable +depends on the project, the team, and the organisation (as well as +preferences). The question is, therefore: > Which branching strategy is the best fit for the Seedcase Project? -## Decision Drivers +## Decision drivers ::: content-hidden List some reasons for why we need to make this decision and what things have arisen that impact work. ::: -With collaborative software development, each developer might have their own way of doing things such as branching, committing, creating pull requests and issues, and reviewing. However, explicitly agreeing on how we do these things will ensure common workflows across developers to help along efficient collaboration. +With collaborative software development, each developer might have their +own way of doing things such as branching, committing, creating pull +requests and issues, and reviewing. However, explicitly agreeing on how +we do these things will ensure common workflows across developers to +help along efficient collaboration. -When a team follows the same workflows, the focus can be shifted from trying to understand *what* each other are currently working on (*how* the problem at hand is solved, and *why* this work is needed) to harnessing each other's expertise and prior experience and improving the quality of everyone's work. +When a team follows the same workflows, the focus can be shifted from +trying to understand *what* each other are currently working on (*how* +the problem at hand is solved, and *why* this work is needed) to +harnessing each other's expertise and prior experience and improving the +quality of everyone's work. For the Seedcase Project, we want to employ a branching strategy that: -1) is simple, transparent, and beginner-friendly -2) enables consistency across contributions through clear guidelines for branching, committing, and reviewing -3) works well with parallel, asynchronous development -4) supports continuous delivery -5) works well for smaller teams +1) is simple, transparent, and beginner-friendly +2) enables consistency across contributions through clear guidelines + for branching, committing, and reviewing +3) works well with parallel, asynchronous development +4) supports continuous delivery +5) works well for smaller teams -## Considered Options +## Considered options ::: content-hidden List and describe some of the options, as well as some of the pros and cons for each option. ::: -In the following sections, we evaluate commonly used branching strategies to decide on which strategy fits the project and our needs the best. These strategies include: **Trunk-based development**, **Git flow**, and **GitHub flow**. +In the following sections, we evaluate commonly used branching +strategies to decide on which strategy fits the project and our needs +the best. These strategies include: **Trunk-based development**, **Git +flow**, and **GitHub flow**. -Note: To keep this decision post relatively short, the strategies and their differences are outlined in a rather simple way, which might result in the loss of some nuances. +Note: To keep this decision post relatively short, the strategies and +their differences are outlined in a rather simple way, which might +result in the loss of some nuances. -### Trunk-Based Development +### Trunk-based development -In [trunk-based development](https://trunkbaseddevelopment.com), developers frequently integrate their code changes into a shared `main` branch, the **trunk**, instead of working on long-lived additional branches that will be merged into `main` less frequently [@tilburg]. This workflow focuses on making smaller, self-contained changes which helps reduce complexity, minimise conflicts, and enable faster review processes and integration [@sooni]. Naturally, this leads to a more continuous integration with frequent merges to the `main` branch. +In [trunk-based development](https://trunkbaseddevelopment.com), +developers frequently integrate their code changes into a shared `main` +branch, the **trunk**, instead of working on long-lived additional +branches that will be merged into `main` less frequently [@tilburg]. +This workflow focuses on making smaller, self-contained changes which +helps reduce complexity, minimise conflicts, and enable faster review +processes and integration [@sooni]. Naturally, this leads to a more +continuous integration with frequent merges to the `main` branch. -Some smaller teams might even avoid branching altogether and commit directly to the trunk/`main` branch. +Some smaller teams might even avoid branching altogether and commit +directly to the trunk/`main` branch. -::: {.columns} -::: {.column} -#### Benefits +::: columns +::: column +#### Benefits -- More continuous integration with frequent merges to the `main` branch -- Focuses on smaller, self-contained changes -- Minimises merge conflicts -- Allows for quick releases -- Works well for smaller teams +- More continuous integration with frequent merges to the `main` + branch +- Focuses on smaller, self-contained changes +- Minimises merge conflicts +- Allows for quick releases +- Works well for smaller teams ::: -::: {.column} + +::: column #### Drawbacks -- Frequent integration requires strong collaboration and communication skills, potentially with frequent sync-up meetings -- Works best with small, self-contained tasks to enable short-lived branches (or omission of additional branches all together) +- Frequent integration requires strong collaboration and communication + skills, potentially with frequent sync-up meetings +- Works best with small, self-contained tasks to enable short-lived + branches (or omission of additional branches all together) ::: ::: -### Git Flow - -A contrast to trunk-based development is the [Git flow](https://nvie.com/posts/a-successful-git-branching-model/). Git flow is a comprehensive branching strategy with two central branches: **`main`** and **`develop`**. In this strategy, the **`main`** branch always reflect a production ready state of the codebase. In contrast, the **`develop`** branch contains the latest development changes for the next release. When the new developments are at a stable point and is ready to be released, all the changes from the `develop` branch will be merged into the `main` branch. As a result, whenever there is a new change to the `main` branch, this is a new release by definition. Each release version will be tagged [@thummala]. - -Besides the two central branches, supporting branches will be created to enable parallel development across contributors. These supporting branches are created for specific purposes, such as adding or modifying features (a *feature* branch) or fixing a critical issue in the code (a *hotfix* branch). -A feature branch must always be created from and merged into the `develop` branch, while a `hotfix` branch is usually created from the `main` branch and is be merged into both `main` and `develop`. - -::: {.columns} -::: {.column} +### Git flow + +A contrast to trunk-based development is the [Git +flow](https://nvie.com/posts/a-successful-git-branching-model/). Git +flow is a comprehensive branching strategy with two central branches: +**`main`** and **`develop`**. In this strategy, the **`main`** branch +always reflect a production ready state of the codebase. In contrast, +the **`develop`** branch contains the latest development changes for the +next release. When the new developments are at a stable point and is +ready to be released, all the changes from the `develop` branch will be +merged into the `main` branch. As a result, whenever there is a new +change to the `main` branch, this is a new release by definition. Each +release version will be tagged [@thummala]. + +Besides the two central branches, supporting branches will be created to +enable parallel development across contributors. These supporting +branches are created for specific purposes, such as adding or modifying +features (a *feature* branch) or fixing a critical issue in the code (a +*hotfix* branch). A feature branch must always be created from and +merged into the `develop` branch, while a `hotfix` branch is usually +created from the `main` branch and is be merged into both `main` and +`develop`. + +::: columns +::: column #### Benefits -- Clear framework offering an explicit shared understanding of the branching and releasing processes -- Clear responsibilities for each branch -- Versioning per definition -- Production versions are easy to navigate through tags +- Clear framework offering an explicit shared understanding of the + branching and releasing processes +- Clear responsibilities for each branch +- Versioning per definition +- Production versions are easy to navigate through tags ::: -::: {.column} + +::: column #### Drawbacks -- Revolves around releases, and we, currently, need a more continuous delivery-like approach -- Complexity due to the number of branches, which could lead to merge conflicts and slow down the development process +- Revolves around releases, and we, currently, need a more continuous + delivery-like approach +- Complexity due to the number of branches, which could lead to merge + conflicts and slow down the development process ::: ::: -### GitHub Flow - -[GitHub flow](https://docs.github.com/en/get-started/quickstart/github-flow) is a simpler branching strategy than Git flow, revolving around the **`main`** branch. The only "hard" rule in this workflow is that anything on the `main` branch is deployable [@githubflowpost]. Whenever new work needs to be done, a new branch with a descriptive name is created from the `main` branch. Like with the Git flow, types of branches include (among others) `feature` and `hotfix` branches. After a new branch has been created, changes are made on this branch with regular pushes and descriptive commit messages. - -When the developer wants feedback, they create a pull request, which their collaborators review. Any suggested changes are addressed and implemented. When the work is complete, the branch can be merged into the `main` branch and is deleted. With this branching strategy, the work on the new branch is deployed as soon as it is merged into `main`. - -::: {.columns} -::: {.column} +### GitHub flow + +[GitHub +flow](https://docs.github.com/en/get-started/quickstart/github-flow) is +a simpler branching strategy than Git flow, revolving around the +**`main`** branch. The only "hard" rule in this workflow is that +anything on the `main` branch is deployable [@githubflowpost]. Whenever +new work needs to be done, a new branch with a descriptive name is +created from the `main` branch. Like with the Git flow, types of +branches include (among others) `feature` and `hotfix` branches. After a +new branch has been created, changes are made on this branch with +regular pushes and descriptive commit messages. + +When the developer wants feedback, they create a pull request, which +their collaborators review. Any suggested changes are addressed and +implemented. When the work is complete, the branch can be merged into +the `main` branch and is deleted. With this branching strategy, the work +on the new branch is deployed as soon as it is merged into `main`. + +::: columns +::: column #### Benefits -- Allows for continuous development and the ability to quickly address issues of all kinds (including security issues, bugs, and small feature requests) -- The same simple processes are used to address smaller and larger developments -- Works well for smaller teams and asynchronous collaboration, common in open-source projects +- Allows for continuous development and the ability to quickly address + issues of all kinds (including security issues, bugs, and small + feature requests) +- The same simple processes are used to address smaller and larger + developments +- Works well for smaller teams and asynchronous collaboration, common + in open-source projects ::: -::: {.column} + +::: column #### Drawbacks -- Does not by definition include releases -- Might be more susceptible to bugs in production (compared to Git flow) because of the lack of dedicated development branches -- Long-living branches can increase the risk of merge conflicts +- Does not by definition include releases +- Might be more susceptible to bugs in production (compared to Git + flow) because of the lack of dedicated development branches +- Long-living branches can increase the risk of merge conflicts ::: ::: -## Decision Outcome +## Decision outcome ::: content-hidden What decision was made, use the form "We decided on CHOICE because of @@ -204,13 +278,17 @@ REASONS." We decided on using the GitHib flow branching strategy because: -1) It is simple and beginner-friendly strategy -2) It is both well-known and well documented, creating clear guidelines that enable consistency across contributions -3) It offers clear guidelines on every step of collaborative development, including branching, committing, and review processes -4) Longer-living branches works well with parallel, asynchronous work -5) The balance between having multiple branches as well as using continuous integration and delivery approaches -6) Not overly complex for a smaller team like ours -7) Allows for continuous development with the same simple processes for both +1) It is simple and beginner-friendly strategy +2) It is both well-known and well documented, creating clear guidelines + that enable consistency across contributions +3) It offers clear guidelines on every step of collaborative + development, including branching, committing, and review processes +4) Longer-living branches works well with parallel, asynchronous work +5) The balance between having multiple branches as well as using + continuous integration and delivery approaches +6) Not overly complex for a smaller team like ours +7) Allows for continuous development with the same simple processes for + both ### Consequences @@ -218,6 +296,15 @@ We decided on using the GitHib flow branching strategy because: List some potential consequences of this decision. ::: -Even though the GitHub flow is the most suitable branching strategy for the Seedcase Project right now, this choice does come with consequences. For example, working on longer-living branches (compared to trunk-based-development) could increase the risk of merge conflicts (which is easier to avoid using trunk-based-development). This strategy also comes without release tagging (as Git flow does), something we might want to implement for Seedcase Software Products later on. - -However, GitHub flow eases the process of parallel, asynchronous development and is ideal for smaller teams like ours. While we deploy continuously, a relatively simples workflow like GitHub flow is the best fit for us. +Even though the GitHub flow is the most suitable branching strategy for +the Seedcase Project right now, this choice does come with consequences. +For example, working on longer-living branches (compared to +trunk-based-development) could increase the risk of merge conflicts +(which is easier to avoid using trunk-based-development). This strategy +also comes without release tagging (as Git flow does), something we +might want to implement for Seedcase software products later on. + +However, GitHub flow eases the process of parallel, asynchronous +development and is ideal for smaller teams like ours. While we deploy +continuously, a relatively simple workflow like GitHub flow is the best +fit for us. diff --git a/why-github-projects.qmd b/why-github-projects.qmd index 6a74aeb..1d8cf67 100644 --- a/why-github-projects.qmd +++ b/why-github-projects.qmd @@ -1,8 +1,7 @@ --- title: "Why GitHub Projects" description: "As a project grows, it becomes both more important and more difficult to keep track of where the project is at. This can be helped by using visualisation and project management tools like GitHub Projects." -author: "Kristiane Beicher" -date: last-modified +date: "2023-11-23" categories: - documentation - github @@ -15,39 +14,59 @@ categories: - workflow --- -## Context and Problem Statement + + +## Context and problem statement The larger a team is, the more important it becomes to keep track of who is doing what and how far they are with certain tasks. One way of creating such an overview is by using visualisation tools, which are designed to create overviews quickly. The question then becomes: > How do we create an overview of our current and upcoming tasks which will allow not only the person working on the task to monitor progress, but also help fellow team members to see where the project is? -## Decision Drivers +## Decision drivers As a team we have been struggling to keep track of who is completing which tasks, and how far along that work is. We have therefore agreed, that we will try to communicate this better internally within the team, not only with frequent commits and reviews, but also utilising the new project tools that GitHub have rolling out. -## Considered Options +## Considered options -### Kanban Boards like Monday.com and Trello +### Kanban boards like Monday.com and Trello There are a number of free options when it comes to visualisation and project management tools specialising in workflows ([Monday.com](https://monday.com/) and Kanban Boards like [Trello](https://trello.com) to mention a couple). Here are some pros and cons. -- Pro: These are dedicated project management tools, so come with lots of features that might be needed for these tasks. -- Cons: - - Most require us to export our GitHub Issues log and rely on using them. - - Will need to learn and integrate another tool/service into our workflow. - - We aren't a large team, so many of the features will be unused by us. +::: {.columns} +::: {.column} +#### Benefits + +- These are dedicated project management tools, so come with lots of features that might be needed for these tasks +::: +::: {.column} +#### Drawbacks + +- Most require us to export our GitHub Issues log and rely on using them +- Will need to learn and integrate another tool/service into our workflow +- We aren't a large team, so many of the features will be unused by us +::: +::: ### GitHub Projects GitHub has a built-in "Projects" feature for project management and visualizations. It comes with [extensive documentation](https://docs.github.com/en/issues/planning-and-tracking-with-projects) and is fairly intuitive to set up. As well as a standard overview it allows for a layout with vertical "status" lanes (Board) for "todo", "in progress", and "in review", as well as Gannt-like features (Roadmap). -- Pros: - - We already heavily use GitHub and use Issues, so it makes sense to not learn another tool/service when we can keep using GitHub. - - It has all the features we need at this point in time. -- Con: GitHub isn't a dedicated project management service, so there might be some features we are missing. +::: {.columns} +::: {.column} +#### Benefits + +- We already heavily use GitHub and use Issues, so it makes sense to not learn another tool/service when we can keep using GitHub +- It has all the features we need at this point in time +::: +::: {.column} +#### Drawbacks + +- GitHub isn't a dedicated project management service, so there might be some features we are missing +::: +::: -## Decision Outcome +## Decision outcome We have decided to use GitHub Projects because we can easily integrate it into our workflow and we don't have to learn another tool. @@ -55,4 +74,4 @@ We'll make heavy use of the two chart options mentioned above, the Board and the As mentioned in our guidelines, we will be working in iterations which are of varied length. The idea is that the Board from GitHub will help us with this team project management workflow. We will set up a board for each iteration (typically from 2-6 weeks) during a team meeting, and then populate it together with tasks and issues that we feel fits with the overall theme of that particular iteration. It is then up to the individual team member to use the Roadmap feature if they feel it will help. - \ No newline at end of file + diff --git a/why-material-design.qmd b/why-material-design.qmd index 4b3f1b5..07ab9c9 100644 --- a/why-material-design.qmd +++ b/why-material-design.qmd @@ -1,8 +1,7 @@ --- title: "Why Material Design" -description: "We aim to utilise existing CSS or UI frameworks instead of building from scratch so Seedcase will look good with minimal effort. Since Material Design lives up to these requirements, we have chosen this framework for Seedcase." -author: "Philip Christiansen" -date: last-modified +description: "We aim to utilise existing CSS or UI frameworks instead of building from scratch so Seedcase software products will look good with minimal effort. Since Material Design lives up to these requirements, we have chosen this framework for our software." +date: "2023-12-15" categories: - user interface - user experience @@ -10,70 +9,125 @@ categories: - style --- -## Context and Problem Statement +## Context and problem statement -The Seedcase software products' frontend should look good with minimal effort. Therefore, we aim to utilise existing CSS or UI frameworks instead of building from scratch. +The front end of Seedcase software products should look good with +minimal effort. Therefore, we aim to utilise existing CSS or UI +frameworks instead of building from scratch. -## Decision Drivers +## Decision drivers The UI framework should: -- Be aesthetically pleasing. -- Integrate well with Figma. The wireframes in Figma should be easy to reproduce in Django templates. -- Be easy to use with Django. Since we use Django and it is a Python framework, we don't want to rely on frameworks that require node/npm or too much JavaScript. Preferably, we want a CSS framework, where CSS classes can be directly added to HTML elements. -- Have a great documentation and community. +- Be aesthetically pleasing. +- Integrate well with Figma. The wireframes in Figma should be easy to + reproduce in Django templates. +- Be easy to use with Django. Since we use Django and it is a Python + framework, we don't want to rely on frameworks that require node/npm + or too much JavaScript. Preferably, we want a CSS framework, where + CSS classes can be directly added to HTML elements. +- Have a great documentation and community. -## Considered Options +## Considered options We have considered the following: ### Bootstrap -[Bootstrap](https://getbootstrap.com/) is one of the older and more widely used CSS frameworks. +[Bootstrap](https://getbootstrap.com/) is one of the older and more +widely used CSS frameworks. -- **Pros**: - - Widely used, lots of support and community. - - Great integration with Django through the Python package [`django-bootstrap5`](https://pypi.org/project/django-bootstrap5/). -- **Cons**: - - Harder to customize individual components (for example, a button). +::: columns +::: column +#### Benefits + +- Widely used, lots of support and community +- Great integration with Django through the Python package + [`django-bootstrap5`](https://pypi.org/project/django-bootstrap5/) +::: + +::: column +#### Drawbacks + +- Harder to customize individual components (for example, a button) +::: +::: ### Material Design -[Material Design](https://m3.material.io/) is a popular framework designed by Google. +[Material Design](https://m3.material.io/) is a popular framework +designed by Google. + +::: columns +::: column +#### Benefits + +- Has multiple implementations, like [Materialize + Web](https://materializeweb.com/) and + [BeerCSS](https://www.beercss.com/) that works well with Django +- Prioritizes CSS over JavaScript +- Very customizable +- Looks very aesthetically pleasing (backed by the strong design + community within Google) +- [Figma](https://www.figma.com/) (which can be used for sketching out + the UI) has great support for Material Design +::: + +::: column +#### Drawbacks -- **Pros**: - - Has multiple implementations, like [Materialize Web](https://materializeweb.com/) and [BeerCSS](https://www.beercss.com/) that works well with Django. - - Prioritizes CSS over JavaScript. - - Very customizable. - - Looks very aesthetically pleasing (backed by the strong design community within Google). - - [Figma](https://www.figma.com/) (used for sketching out the UI) has great support for Material Design. -- **Cons**: - - Has multiple implementations, which might take time to decide on. +- Has multiple implementations, which might take time to decide on +::: +::: ### Tailwind -[Tailwind](https://tailwindcss.com/) is a popular framework that allows a high level of customisability. +[Tailwind](https://tailwindcss.com/) is a popular framework that allows +a high level of customisability. -- **Pros**: - - CSS only. - - Very highly customisable. -- **Cons**: - - Requires time and skill to customize - - Relies on [Node.js](https://nodejs.org/en) (via [npm](https://www.npmjs.com/)) which is an additional dependency and needs time to learn to use +::: columns +::: column +#### Benefits + +- CSS only +- Very highly customisable +::: + +::: column +#### Drawbacks + +- Requires time and skill to customize +- Relies on [Node.js](https://nodejs.org/en) (via + [npm](https://www.npmjs.com/)) which is an additional dependency and + needs time to learn to use +::: +::: ### Bulma [Bulma](https://bulma.io/) is a simple CSS or Sass only framework. -- **Pros**: - - Seems relatively easy to use. -- **Cons**: - - Requires Node.js (via npm) to install. +::: columns +::: column +#### Benefits + +- Seems relatively easy to use +::: + +::: column +#### Drawbacks + +- Requires Node.js (via npm) to install +::: +::: -## Decision Outcome +## Decision outcome -We decided on Material Design because it has great integration with existing UI/UX (like Figma), looks amazing (has the design team at Google backing it's development), is widely used, and customizable. +We decided on Material Design because it has great integration with +existing UI/UX (like Figma), looks amazing (has the design team at +Google backing it's development), is widely used, and customizable. ### Consequences -- There is better Django integration with Bootstrap, so we might need to spend some time properly integrating Material Design. \ No newline at end of file +- There is better Django integration with Bootstrap, so we might need + to spend some time properly integrating Material Design diff --git a/why-mit-license.qmd b/why-mit-license.qmd index 569b3e9..eb73e8a 100644 --- a/why-mit-license.qmd +++ b/why-mit-license.qmd @@ -2,7 +2,6 @@ title: "Why an MIT License" description: | Open and permissive licensing of copyrighted content is a way to increase use of a software product, ease collaboration and re-use, and sharing intellectual ideas with others. This post contains our reasons for choosing the MIT License, which is a very permissive copyright license. -author: "Kristiane Beicher" date: "2023-04-01" date-modified: last-modified categories: @@ -11,51 +10,136 @@ categories: - software-architecture --- -## Context and Problem Statement + -When developing a new piece of software it is important to consider the following question as early as possible. +## Context and problem statement -> What kind of re-use will we ultimately allow other developers to make of our software? +When developing a new piece of software it is important to consider the +following question as early as possible. -In order to control this use, it is important to have considered which license type we want our software to be available under, as this will tell the rest of the development community what they can (and can't) do with it. +> What kind of re-use will we ultimately allow other developers to make +> of our software? -## Decision Drivers +In order to control this use, it is important to have considered which +license type we want our software to be available under, as this will +tell the rest of the development community what they can (and can't) do +with it. -Although no license means that a piece of software on GitHub will be under exclusive copyright, leaving our code without one will make it difficult for other users to (easily) (re-)use, modify, contribute, or enhance our software due to copyright reasons. Our mission isn't only to build a piece of software; we also aim to develop a creative community around Seedcase and the topics we work on. We want people to be able to freely and smoothly contribute enhancements and other improvements that can be incorporated into future releases of Seedcase. It is also our intention to make the Seedcase software available to commercial enterprises, which means that we need to carefully consider which license we adopt. +## Decision drivers -## Considered Options +Although no license means that a piece of software on GitHub will be +under exclusive copyright, leaving our code without one will make it +difficult for other users to (easily) (re-)use, modify, contribute, or +enhance our software due to copyright reasons. Our mission isn't only to +build a piece of software; we also aim to develop a creative community +around the Seedcase Project and the topics we work on. We want people to +be able to freely and smoothly contribute enhancements and other +improvements that can be incorporated into future releases of Seedcase +software products. It is also our intention to make the Seedcase +software available to commercial enterprises, which means that we need +to carefully consider which license we adopt. -The Open Source Initiative (OSI) [approves](https://opensource.org/licenses) a specific set of licenses that determine whether a project can be called "open source". These licenses are our starting point on deciding which license to use and how permissive we want it to be, in terms of who can work on our code and how it can be used. +## Considered options -The primary license is the one that governs how our code can be used, modified, and shared, which is described more below. For managing copyright of contributed code from users who are external to the project, agreements could include either a Contributor License Agreement (CLA), a Developer Certificate of Origin (DCO), or neither of those, which we discussion below as well. +The Open Source Initiative (OSI) +[approves](https://opensource.org/licenses) a specific set of licenses +that determine whether a project can be called "open source". These +licenses are our starting point on deciding which license to use and how +permissive we want it to be, in terms of who can work on our code and +how it can be used. -### Software licenses - -Overall, the open source community have licenses that work along two strands, **permissive** and **copy-left**. Both of these "allow software to be freely used, modified, and shared" (see more detail on the [OSI](https://opensource.org/licenses) website). We will be using the OSI's definition of free software that among other things covers the source code being available to download and read/study, to allow for derived works to be created and distributed without violating the given license. +The primary license is the one that governs how our code can be used, +modified, and shared, which is described more below. For managing +copyright of contributed code from users who are external to the +project, agreements could include either a Contributor License Agreement +(CLA), a Developer Certificate of Origin (DCO), or neither of those, +which we discussion below as well. -The **copy-Left licenses** generally state that if a third party makes changes to the existing product, or incorporates the code alongside another code set, then the resulting software must also be available under the same license. This is the broadest definition of free software, as it forces any subsequent development to be shared for free (although most of those licenses state that you are allowed to modify code for own use, the copy-left license only comes into play if you make your modifications available outside your organisation). Examples of Copy-Left licenses are [EUPL-1.2](https://joinup.ec.europa.eu/sites/default/files/custom-page/attachment/2020-03/EUPL-1.2%20EN.txt), [GPL](https://www.gnu.org/licenses/gpl-3.0.en.html), and [LGPL](https://www.gnu.org/licenses/lgpl-3.0.en.html). +### Software licenses -The **permissive licenses** gives you all the above mentioned rights, but they do not enforce that derived works or new works created by taking bits of source code from the original product are made available under the same license. These type of licenses are generally seen as more friendly to commercial enterprises as they will allow companies to use bits of code in proprietary software without having to release the source code for free. Examples of Permissive licenses are [Apache](https://www.apache.org/licenses/LICENSE-2.0), BSD (no matter the number of clauses, e.g., [BSD 2-Clause](https://opensource.org/license/bsd-2-clause/) or [BSD 3-Clause](https://opensource.org/license/bsd-3-clause/)), and [MIT](https://opensource.org/license/mit/). +Overall, the open source community have licenses that work along two +strands, **permissive** and **copy-left**. Both of these "allow software +to be freely used, modified, and shared" (see more detail on the +[OSI](https://opensource.org/licenses) website). We will be using the +OSI's definition of free software that among other things covers the +source code being available to download and read/study, to allow for +derived works to be created and distributed without violating the given +license. + +The **copy-Left licenses** generally state that if a third party makes +changes to the existing product, or incorporates the code alongside +another code set, then the resulting software must also be available +under the same license. This is the broadest definition of free +software, as it forces any subsequent development to be shared for free +(although most of those licenses state that you are allowed to modify +code for own use, the copy-left license only comes into play if you make +your modifications available outside your organisation). Examples of +Copy-Left licenses are +[EUPL-1.2](https://joinup.ec.europa.eu/sites/default/files/custom-page/attachment/2020-03/EUPL-1.2%20EN.txt), +[GPL](https://www.gnu.org/licenses/gpl-3.0.en.html), and +[LGPL](https://www.gnu.org/licenses/lgpl-3.0.en.html). + +The **permissive licenses** gives you all the above mentioned rights, +but they do not enforce that derived works or new works created by +taking bits of source code from the original product are made available +under the same license. These type of licenses are generally seen as +more friendly to commercial enterprises as they will allow companies to +use bits of code in proprietary software without having to release the +source code for free. Examples of Permissive licenses are +[Apache](https://www.apache.org/licenses/LICENSE-2.0), BSD (no matter +the number of clauses, e.g., [BSD +2-Clause](https://opensource.org/license/bsd-2-clause/) or [BSD +3-Clause](https://opensource.org/license/bsd-3-clause/)), and +[MIT](https://opensource.org/license/mit/). ### CLA versus DCO -Some open source projects are asking contributors to sign up to a Contributor License Agreement (CLA) or, alternatively, a Developer Certificate of Origin (DCO). - -Looking at a number of **CLAs** (in particular [Threema](https://threema.ch/en/open-source/cla), [Meta](https://code.facebook.com/cla), and [ImageWorks](https://www.imageworks.com/technology/opensource/cla)), it seems that these projects are mainly concerned with the following: - -- A person submitting code that they are not the copyright holder for. -- Withdrawal of the right to use the submitted code. -- The need to apply for patents in future for parts or all of the source code. -- A change in the type of license that the source code was given at the time of contribution. - -There are also some agreements that touch on the subject of loss and damages that may arise from the use of a particular section of code, as well as how a request for support will be dealt with in future. - -An alternative to a CLA is a **DCO**. The **DCO** was first employed by the Linux Foundation in 2004 and is basically a short document that confirms that the person contributing code is allowed to do so, gives permission for the project to subsequently use it, by adding a Signed-off-by line to their commit message (for an example see the [BeeWare projects DCO](https://beeware.org/contributing/how/dco/what/)). - -## Decision Outcome - -It is in our stated [goals](https://seedcase-project.org/about) that the Seedcase software is available for commercial enterprises as well as academic/healthcare organizations and groups. Aligning with our stated [Guiding Principles](https://seedcase-project.org/about.html#principles), we will use a **permissive** license as it will be the best fit for the Seedcase project. Of the permissive license types we will go with the MIT License as it is the most permissive and easiest to understand and use. +Some open source projects are asking contributors to sign up to a +Contributor License Agreement (CLA) or, alternatively, a Developer +Certificate of Origin (DCO). + +Looking at a number of **CLAs** (in particular +[Threema](https://threema.ch/en/open-source/cla), +[Meta](https://code.facebook.com/cla), and +[ImageWorks](https://www.imageworks.com/technology/opensource/cla)), it +seems that these projects are mainly concerned with the following: + +- A person submitting code that they are not the copyright holder for. +- Withdrawal of the right to use the submitted code. +- The need to apply for patents in future for parts or all of the + source code. +- A change in the type of license that the source code was given at + the time of contribution. + +There are also some agreements that touch on the subject of loss and +damages that may arise from the use of a particular section of code, as +well as how a request for support will be dealt with in future. + +An alternative to a CLA is a **DCO**. The **DCO** was first employed by +the Linux Foundation in 2004 and is basically a short document that +confirms that the person contributing code is allowed to do so, gives +permission for the project to subsequently use it, by adding a +Signed-off-by line to their commit message (for an example see the +[BeeWare projects DCO](https://beeware.org/contributing/how/dco/what/)). + +## Decision outcome + +It is in our stated [goals](https://seedcase-project.org/about) that +Seedcase software is available for commercial enterprises as well as +academic/healthcare organizations and groups. Aligning with our stated +[Guiding +Principles](https://seedcase-project.org/about.html#principles), we will +use a **permissive** license as it will be the best fit for the Seedcase +Project. Of the permissive license types we will go with the MIT License +as it is the most permissive and easiest to understand and use. ### Consequences -Currently, we're not sure if we need to implement a CLA before people outside the team contribute to the code. However, we will likely implementing a **DCO** that future contributors will need to agree to before making a contribution to the project. This could be done either by checking that a commit contains the signed-off-by clause before merging it, or by implementing something like the [GitHub App DCO](https://github.com/apps/dco). The license text itself is available [here](https://developercertificate.org). +Currently, we're not sure if we need to implement a CLA before people +outside the team contribute to the code. However, we will likely +implementing a **DCO** that future contributors will need to agree to +before making a contribution to the project. This could be done either +by checking that a commit contains the signed-off-by clause before +merging it, or by implementing something like the [GitHub App +DCO](https://github.com/apps/dco). The license text itself is available +[here](https://developercertificate.org). diff --git a/why-poetry.qmd b/why-poetry.qmd index 913b3cd..e03fb49 100644 --- a/why-poetry.qmd +++ b/why-poetry.qmd @@ -1,105 +1,180 @@ --- title: "Why Poetry" description: "Our reasons for using Poetry for managing Python package dependencies when building Django and Python projects." -author: "Luke W. Johnston" -date: last-modified +date: "2024-01-29" categories: - package dependencies - virtual environments - python --- -## Context and Problem Statement +## Context and problem statement + +Managing the packages we depend on (e.g. Django) in Python isn't +"simply" installing it on your computer. The issue with installing +Python packages on your computer is dependency conflicts that occur, +where the "dependency trees" of one package require a different +dependency tree than another one. So installing a package that requires +a specific version of one package, while another package you already +have installed requires another version can cause system problems. + +The solution to this problem is by using "virtual environments" in +Python. These are environments that are separate from the rest of the +system and can install any packages without impacting other +environments. + +There are multiple ways of creating these virtual environments and +managing package dependencies, and the optional solution depends on the +project. + +## Decision drivers + +- Package dependency management is a critical task, so we need a tool + for it. +- Ensuring we have some way of building our Python projects in a way + that is less likely to be a "it works on my computer" issue. + +## Considered options + +There are (unfortunately) multiple tools to manage package dependencies +in Python, for example, listed at [Python Packaging User +Guide](https://packaging.python.org/en/latest/tutorials/managing-dependencies/#other-tools-for-application-dependency-management) +and at [Awesome Python](https://python.libhunt.com/poetry-alternatives). +There are also comparison sites like [Ritza +Articles](https://ritza.co/articles/gen-articles/pipenv-vs-virtualenv-vs-poetry-vs-pyenv-vs-pip/), +[warp](https://www.warp.dev/blog/prose-about-poetry), and +[this](https://dev.to/adamghill/python-package-manager-comparison-1g98), +and +[this](https://dev.to/frostming/a-review-pipenv-vs-poetry-vs-pdm-39b4) +at [dev.to](https://dev.to/) that go into more detail about many of +these tools. -Managing the packages we depend on (e.g. Django) in Python isn't "simply" installing it on your computer. The issue with installing Python packages on your computer is dependency conflicts that occur, where the "dependency trees" of one package require a different dependency tree than another one. So installing a package that requires a specific version of one package, while another package you already have installed requires another version can cause system problems. +We'll only cover these more popular tools: -The solution to this problem is by using "virtual environments" in Python. These are environments that are separate from the rest of the system and can install any packages without impacting other environments. +- [Pipenv](https://pipenv.pypa.io/en/latest/index.html) +- [Poetry](https://python-poetry.org/) +- [Hatch](https://hatch.pypa.io/latest/version/) +- [PDM](https://pdm-project.org/latest/usage/dependency/) -There are multiple ways of creating these virtual environments and managing package dependencies, and the optional solution depends on the project. +### Pipenv -## Decision Drivers +[Pipenv](https://pipenv.pypa.io/en/latest/index.html) was designed to +combine the existing functionality of `pip` and `virtualenv`, rather +than being designed and built specifically for the purpose of package +management. -- Package dependency management is a critical task, so we need a tool for it. -- Ensuring we have some way of building our Python projects in a way that is less likely to be a "it works on my computer" issue. +::: columns +::: column +#### Benefits -## Considered Options +- Is very popular and widely used +- Has been around for a while +- Only handles package dependencies (no other features) -There are (unfortunately) multiple tools to manage package dependencies in Python, for example, listed at [Python Packaging User Guide](https://packaging.python.org/en/latest/tutorials/managing-dependencies/#other-tools-for-application-dependency-management) and at [Awesome Python](https://python.libhunt.com/poetry-alternatives). There are also comparison sites like [Ritza Articles](https://ritza.co/articles/gen-articles/pipenv-vs-virtualenv-vs-poetry-vs-pyenv-vs-pip/), [warp](https://www.warp.dev/blog/prose-about-poetry), and [this](https://dev.to/adamghill/python-package-manager-comparison-1g98), and [this](https://dev.to/frostming/a-review-pipenv-vs-poetry-vs-pdm-39b4) at [dev.to](https://dev.to/) that go into more detail about many of these tools. +::: -We'll only cover these more popular tools: +::: column +#### Drawbacks -- [Pipenv](https://pipenv.pypa.io/en/latest/index.html) -- [Poetry](https://python-poetry.org/) -- [Hatch](https://hatch.pypa.io/latest/version/) -- [PDM](https://pdm-project.org/latest/usage/dependency/) +- Design is a bit older and not as intuitive/clear to use +- Documentation is a bit too verbose/technical +- Package caching doesn't seem to be well designed/robust, so packages could get unnecessarily re-installed +- Only handles package dependency management, which means we need another tool to develop software (like a Python package) -### Pipenv +::: +::: -[Pipenv](https://pipenv.pypa.io/en/latest/index.html) was designed to combine the existing functionality of `pip` and `virtualenv`, rather than being designed and built specifically for the purpose of package management. +### Poetry -- **Pros**: - - Is very popular and widely used - - Has been around for a while - - Only handles package dependencies (no other features) -- **Cons**: - - Design is a bit older and not as intuitive/clear to use - - Documentation is a bit too verbose/technical - - Package caching doesn't seem to be well designed/robust, so packages could get unnecessarily re-installed - - Only handles package dependency management, which means we need another tool to develop software (like a Python package) +[Poetry](https://python-poetry.org/) was built and designed to address +some of the short comings of pipenv and is specifically designed with +package management and project development in mind. -### Poetry +::: columns +::: column +#### Benefits +- Popular and widely used +- Very well designed website and documentation +- Handles package dependencies with lock files (detailed list of packages and versioning) +- Can set up and help manage a Python project (e.g. Python package) +- Designed from the ground up to consider the needs of package development and dependency resolution +- Allows for external plug-ins for further customization +- Similar dependency management to other languages +- Installable with `pipx` +- Integrates well with existing IDE/editors (PyCharm and VSCode) + +::: + +::: column +#### Drawbacks -[Poetry](https://python-poetry.org/) was built and designed to address some of the short comings of pipenv and is specifically designed with package management and project development in mind. - -- **Pros**: - - Popular and widely used - - Very well designed website and documentation - - Handles package dependencies with lock files (detailed list of packages and versioning) - - Can set up and help manage a Python project (e.g. Python package) - - Designed from the ground up to consider the needs of package development and dependency resolution - - Allows for external plug-ins for further customization - - Similar dependency management to other languages - - Installable with `pipx` - - Integrates well with existing IDE/editors (PyCharm and VSCode) -- **Cons**: - - Installation and resolving package dependency trees (so there are no conflicts) can be a bit slow - - Not completely PEP compliant (not yet support [PEP 621](https://peps.python.org/pep-0621/), but an Issue on it is [here](https://github.com/python-poetry/roadmap/issues/3)), though this isn't a critical problem +- Installation and resolving package dependency trees (so there are no conflicts) can be a bit slow +- Not completely PEP compliant (not yet support [PEP 621](https://peps.python.org/pep-0621/), but an Issue on it is [here](https://github.com/python-poetry/roadmap/issues/3)), though this isn't a critical problem + +::: +::: ### Hatch -[Hatch](https://hatch.pypa.io/latest/version/), like Poetry, was designed to manage package dependencies and Python projects. - -- **Pros**: - - Very similar to Poetry - - Is fully PEP-compliant - - Is relatively new - - Is very opinionated - - Good documentation - - Now maintained under the official PyPA - - Because of being PEP-compliant and hosted by PyPA, may be the better option in the future -- **Cons**: - - Is very opinionated - - Is relatively new, so might still be working through things - - Not as widely used compared to the others +[Hatch](https://hatch.pypa.io/latest/version/), like Poetry, was +designed to manage package dependencies and Python projects. + +::: columns +::: column +#### Benefits + +- Very similar to Poetry +- Is fully PEP-compliant +- Is relatively new +- Is very opinionated +- Good documentation +- Now maintained under the official PyPA +- Because of being PEP-compliant and hosted by PyPA, may be the better + option in the future +::: + +::: column +#### Drawbacks + +- Is very opinionated +- Is relatively new, so might still be working through things +- Not as widely used compared to the others +::: +::: ### PDM -[PDM](https://pdm-project.org/latest/usage/dependency/), like both Poetry and Hatch, is designed for managing packages and Python projects. +[PDM](https://pdm-project.org/latest/usage/dependency/), like both +Poetry and Hatch, is designed for managing packages and Python projects. + +::: columns +::: column +#### Benefits + +- Fully PEP-compliant +- Decent documentation +::: + +::: column +#### Drawbacks -- **Pros**: - - Fully PEP-compliant - - Decent documentation -- **Cons**: - - Relatively new - - Not as widely used or as popular - - Doesn't have distribution specific installation builds (need to use `curl` to install, which isn't the most secure way of installing) - - Can't install through `pipx` +- Relatively new +- Not as widely used or as popular +- Doesn't have distribution specific installation builds (need to use + `curl` to install, which isn't the most secure way of installing) +- Can't install through `pipx` +::: +::: -## Decision Outcome +## Decision outcome -We decided on Poetry because it has amazing documentation, is well-designed, and is very popular and widely used. +We decided on Poetry because it has amazing documentation, is +well-designed, and is very popular and widely used. ### Consequences -- Because Poetry isn't fully PEP compliant, we might encounter some issues -- Doesn't have the "official" support (hosted on the GitHub PyPA organization) that Hatch has, so we might reconsider the decision to use Poetry at a future date +- Because Poetry isn't fully PEP compliant, we might encounter some + issues +- Doesn't have the "official" support (hosted on the GitHub PyPA + organization) that Hatch has, so we might reconsider the decision to + use Poetry at a future date diff --git a/why-polyrepo.qmd b/why-polyrepo.qmd index 3b501a5..dea8af7 100644 --- a/why-polyrepo.qmd +++ b/why-polyrepo.qmd @@ -1,8 +1,7 @@ --- title: "Why poly-repo" description: "Our reasons for structuring projects (both software and websites) in a poly-repo rather than mono-repo style." -author: "Luke W. Johnston" -date: last-modified +date: "2023-12-05" categories: - repositories - organization @@ -10,56 +9,121 @@ categories: - management --- -## Context and Problem Statement - -The core issue and question here is: - -> How do we decide to structure and organize our projects, both software products as well as documentation and training material? - -We are ultimately building a final, single software product that can be installed on servers and used as is. However, some components of our software could be useful on their own. So we've started building another product as a Git repo. Which has lead us into this issue and question, since we don't want to start doing something major without considering why we are doing it and what the impact might be. And then coming to a conscious and agreed upon decision. - -We also will be working on other, side projects for Steno Aarhus and other potential projects related, but not connected to the core Seedcase product. For example, we will be helping design and build CPR validation checks or volunteer databases. We will be creating multiple repositories/projects, so if we have a streamlined approach and workflow to creating and developing projects in this way, of having multiple repositories for different projects, it would be easier to manage. - -See some discussion of the beginning of this issue [here](https://github.com/seedcase-project/seedcase-registry/pull/9). - -## Decision Drivers - -- Tracking and managing projects: - - Looking over the list of issues in any given project right now can feel overwhelming because of the number of issues (the list will only grow). Trying to look through the list to find ones relevant to the component of the project you are working on can be a bit of an "analysis paralysis". - - Tracking issues in sub-projects/components within a single repo means making heavily use of custom labels, which can be a challenge from a management point of view. - - I'd like to eventually get to a place where we can dedicate a chunk of time to working on one specific project. My inspiration for how to do that comes from the tidyverse team at RStudio/Posit. They let issues build up in an R package/project over time before dedicating time to working through as many of those issues as possible. Once done, they switch to another project that has a lot of issues. -- Setting up continuous integration and deployment: We haven't yet set up CI/CD, but a lot of standard templates are based on a one repo is one package/app/product approach (for instance, CI's for testing and building Python packages or deploying Docker images to DockerHub). -- We're already splitting projects into other repos. - - We're building a separate `seedcase-registry` product, which is the data project registration component of `seedcase`. This product will be imported/loaded into `seedcase`. -- Open source projects are usually a "one-repo is one-product/output" format (e.g. R or Python package). Contributors will likely be people who have experience working in open source communities and projects. -- We are starting to and will be creating and building multiple products, both within the overall aim of Seedcase, but also sub-projects at Steno and potential (independent) extensions to Seedcase. -- Providing common repository templates, build processes, and CI/CD for Steno Aarhus (and others in the future), so we'll need to build these anyway. -- We need to consider the workflow for the team over the long term. Some decisions make more sense in the short term, but in the long term don't make sense. - -## Considered Options - -There are multiple existing posts about this exact issue of mono- vs poly-repos, which I am listing below, that helped me write up this decision. - -- [Monorepo vs polyrepo](https://github.com/joelparkerhenderson/monorepo-vs-polyrepo) -- [StackOverflow: Where keep deployment files in Multi Container, Multi Repository Project?](https://stackoverflow.com/questions/47502859/where-keep-deployment-files-in-multi-container-multi-repository-project) -- [StackOverflow: Git repository setup for a Docker application consisting of multiple repositories](https://stackoverflow.com/questions/49918636/git-repository-setup-for-a-docker-application-consisting-of-multiple-repositorie) -- [Monorepo vs Multi-repo](https://kinsta.com/blog/monorepo-vs-multi-repo/) -- [CircleCI: Benefits and challenges of monorepo development practices](https://circleci.com/blog/monorepo-dev-practices/) -- [Monorepos: Please don't!](https://medium.com/@mattklein123/monorepos-please-dont-e9a279be011b) -- [Coupling in Microservices, Part 2: Single vs. Multi-Repo](https://medium.com/flippengineering/coupling-in-microservices-part-2-single-vs-multi-repo-35c5d5f3057b) -- [Earthly: Monorepo vs polyrepo](https://earthly.dev/blog/monorepo-vs-polyrepo/) -- [Mono-Repo vs Multi-Repo: Throwing Light On Code Repository Strategies](https://geekflare.com/code-repository-strategies/) -- [Monorepo vs multirepo decision: Using monorepos for rapid iteration, polyrepos for sustained stability](https://github.com/joelparkerhenderson/architecture-decision-record/tree/main/examples/monorepo-vs-multirepo) -- [Monorepos and the Fallacy of Scale](https://presumably.de/monorepos-and-the-fallacy-of-scale.html) -- [Monorepo Vs Polyrepo Architecture: A Comparison For Effective Software Development](https://intuji.com/monorepo-vs-polyrepo-architecture/) + + +## Context and problem statement + +The core issue and question here is: + +> How do we decide to structure and organize our projects, both software +> products as well as documentation and training material? + +We initially set out to build a single final software product that can +be installed on servers and used as is. However, some components of our +software could be useful on their own. So we've started building another +product as a Git repo. Which has lead us into this issue and question, +since we don't want to start doing something major without considering +why we are doing it and what the impact might be. And then coming to a +conscious and agreed upon decision. + +We also will be working on other, side projects for Steno Aarhus and +other potential projects related, but not connected to the core Seedcase +product. For example, we will be helping design and build CPR validation +checks or volunteer databases. We will be creating multiple +repositories/projects, so if we have a streamlined approach and workflow +to creating and developing projects in this way, of having multiple +repositories for different projects, it would be easier to manage. + +See some discussion of the beginning of this issue +[here](https://github.com/seedcase-project/seedcase-registry/pull/9). + +## Decision drivers + +- Tracking and managing projects: + - Looking over the list of issues in any given project right now + can feel overwhelming because of the number of issues (the list + will only grow). Trying to look through the list to find ones + relevant to the component of the project you are working on can + be a bit of an "analysis paralysis". + - Tracking issues in sub-projects/components within a single repo + means making heavily use of custom labels, which can be a + challenge from a management point of view. + - I'd like to eventually get to a place where we can dedicate a + chunk of time to working on one specific project. My inspiration + for how to do that comes from the tidyverse team at + RStudio/Posit. They let issues build up in an R package/project + over time before dedicating time to working through as many of + those issues as possible. Once done, they switch to another + project that has a lot of issues. +- Setting up continuous integration and deployment: We haven't yet set + up CI/CD, but a lot of standard templates are based on a one repo is + one package/app/product approach (for instance, CI's for testing and + building Python packages or deploying Docker images to DockerHub). +- We're already splitting projects into other repos. + - We're building a separate `seedcase-registry` product, which is + the data project registration component of `seedcase`. This + product will be imported/loaded into `seedcase`. +- Open source projects are usually a "one-repo is one-product/output" + format (e.g. R or Python package). Contributors will likely be + people who have experience working in open source communities and + projects. +- We are starting to and will be creating and building multiple + products, both within the overall aim of the Seedcase Project, but + also sub-projects at Steno and potential (independent) extensions to + Seedcase products. +- Providing common repository templates, build processes, and CI/CD + for Steno Aarhus (and others in the future), so we'll need to build + these anyway. +- We need to consider the workflow for the team over the long term. + Some decisions make more sense in the short term, but in the long + term don't make sense. + +## Considered options + +There are multiple existing posts about this exact issue of mono- vs +poly-repos, which I am listing below, that helped me write up this +decision. + +- [Monorepo vs + polyrepo](https://github.com/joelparkerhenderson/monorepo-vs-polyrepo) +- [StackOverflow: Where keep deployment files in Multi Container, + Multi Repository + Project?](https://stackoverflow.com/questions/47502859/where-keep-deployment-files-in-multi-container-multi-repository-project) +- [StackOverflow: Git repository setup for a Docker application + consisting of multiple + repositories](https://stackoverflow.com/questions/49918636/git-repository-setup-for-a-docker-application-consisting-of-multiple-repositorie) +- [Monorepo vs + Multi-repo](https://kinsta.com/blog/monorepo-vs-multi-repo/) +- [CircleCI: Benefits and challenges of monorepo development + practices](https://circleci.com/blog/monorepo-dev-practices/) +- [Monorepos: Please + don't!](https://medium.com/@mattklein123/monorepos-please-dont-e9a279be011b) +- [Coupling in Microservices, Part 2: Single vs. + Multi-Repo](https://medium.com/flippengineering/coupling-in-microservices-part-2-single-vs-multi-repo-35c5d5f3057b) +- [Earthly: Monorepo vs + polyrepo](https://earthly.dev/blog/monorepo-vs-polyrepo/) +- [Mono-Repo vs Multi-Repo: Throwing Light On Code Repository + Strategies](https://geekflare.com/code-repository-strategies/) +- [Monorepo vs multirepo decision: Using monorepos for rapid + iteration, polyrepos for sustained + stability](https://github.com/joelparkerhenderson/architecture-decision-record/tree/main/examples/monorepo-vs-multirepo) +- [Monorepos and the Fallacy of + Scale](https://presumably.de/monorepos-and-the-fallacy-of-scale.html) +- [Monorepo Vs Polyrepo Architecture: A Comparison For Effective + Software + Development](https://intuji.com/monorepo-vs-polyrepo-architecture/) Almost all sources say, which you choose depends on your own situation. ### Mono-repo -A mono-repo is where all code for a product is kept and developed in one Git repository. Many large companies like Google and Facebook use a mono-repo approach to developing their software products. This approach looks a bit like this, where each project is a folder under the main repo: +A mono-repo is where all code for a product is kept and developed in one +Git repository. Many large companies like Google and Facebook use a +mono-repo approach to developing their software products. This approach +looks a bit like this, where each project is a folder under the main +repo: -``` +``` main/ ├── .git/ ├── project1/ @@ -79,38 +143,67 @@ main/ └── build ``` -**Pros:** +**Pros:** -- It works quite well when the core software service will inevitably be deployed and used as a single service, for instance with Google's Search Engine. -- It's a bit easier for smaller teams to use a mono-repo approach since it allows the team to move a bit faster in developing the product. -- Project management and issue tracking all happens in one location, so it's easier for a dedicated coordinator or manager to track the project. -- Components can be tightly coupled and easily updated within a mono-repo. -- Single codebase is enticing, since it theoretically makes it easier to get onboarded, manage, and track progress on a project. -- All code is in one location, so finding code might be easier. +- It works quite well when the core software service will inevitably + be deployed and used as a single service, for instance with Google's + Search Engine. +- It's a bit easier for smaller teams to use a mono-repo approach + since it allows the team to move a bit faster in developing the + product. +- Project management and issue tracking all happens in one location, + so it's easier for a dedicated coordinator or manager to track the + project. +- Components can be tightly coupled and easily updated within a + mono-repo. +- Single codebase is enticing, since it theoretically makes it easier + to get onboarded, manage, and track progress on a project. +- All code is in one location, so finding code might be easier. **Cons:** -- Paradoxically, it is harder for smaller teams to manage the complexity of a mono-repo because of the reasons below. -- Within the open source world, mono-repo's are not common, so contributors might not know how to navigate the repo. -- Tend to require custom built CI/CD tooling rather than make use the many open source templates available. -- Versioning of the software happens all at once, so a change in one component requires a version update, even though other components don't change. -- Project and issue management all happens in the same repo, so for a small team with many many tasks to manage, it gets overwhelming to focus on what needs to be done. -- If one component could be used as an independent product, it would have to be split out of the mono-repo, otherwise people would have to install the whole product just to use the small component they actually need or want. -- Deploying and testing may take longer because you have to deploy and test the *whole* repo, so if a small change was made, that would trigger long deployment and testing times. -- Effective management of a project may require more complex git branching processes. -- It's more difficult to manage ownership of code on a per-directory level. -- If a bug or conflict occurs, it breaks the whole product. -- As a codebase grows, the complexity involved in managing a mono-repo can increase substantially. - -### Poly-repo +- Paradoxically, it is harder for smaller teams to manage the + complexity of a mono-repo because of the reasons below. +- Within the open source world, mono-repo's are not common, so + contributors might not know how to navigate the repo. +- Tend to require custom built CI/CD tooling rather than make use the + many open source templates available. +- Versioning of the software happens all at once, so a change in one + component requires a version update, even though other components + don't change. +- Project and issue management all happens in the same repo, so for a + small team with many many tasks to manage, it gets overwhelming to + focus on what needs to be done. +- If one component could be used as an independent product, it would + have to be split out of the mono-repo, otherwise people would have + to install the whole product just to use the small component they + actually need or want. +- Deploying and testing may take longer because you have to deploy and + test the *whole* repo, so if a small change was made, that would + trigger long deployment and testing times. +- Effective management of a project may require more complex git + branching processes. +- It's more difficult to manage ownership of code on a per-directory + level. +- If a bug or conflict occurs, it breaks the whole product. +- As a codebase grows, the complexity involved in managing a mono-repo + can increase substantially. + +### Poly-repo (also known as multi-repo) -While many large companies use a mono-repo approach, there are also large companies who use a poly-repo approach, like Amazon. Within the open source world, poly-repos are extremely common. For instance, the [tidyverse](https://github.com/orgs/tidyverse/repositories), [ROpenSci](https://ropensci.org/packages/), or [Gen3](https://github.com/orgs/uc-cdis/repositories) teams develop dozens of packages, and their teams are quite small. +While many large companies use a mono-repo approach, there are also +large companies who use a poly-repo approach, like Amazon. Within the +open source world, poly-repos are extremely common. For instance, the +[tidyverse](https://github.com/orgs/tidyverse/repositories), +[ROpenSci](https://ropensci.org/packages/), or +[Gen3](https://github.com/orgs/uc-cdis/repositories) teams develop +dozens of packages, and their teams are quite small. This structure looks a bit like: -``` +``` project1/ ├── .git/ ├── tests/ @@ -131,35 +224,59 @@ project3/ └── build ``` -In many ways, the pros and cons are the reverse with the mono-repo, but there are also other considerations included here. +In many ways, the pros and cons are the reverse with the mono-repo, but +there are also other considerations included here. **Pros:** -- Testing and deployment per unit of change in code is faster. -- Versioning of components is easier since each component is its own repo. -- Project management on a repo-level is easier, since issues and progress is smaller and more focused. -- Standard open source templates for CI/CD and other basic repo and build files can be used. -- Onboarding for contributors is easier if they come from the open source community. -- Open source projects very often follow this approach, so its easier to draw inspiration and learn how other projects do things. -- Using version control, managing the commit history, and working with pull requests can be easier, since they will be specific to the project. +- Testing and deployment per unit of change in code is faster. +- Versioning of components is easier since each component is its own + repo. +- Project management on a repo-level is easier, since issues and + progress is smaller and more focused. +- Standard open source templates for CI/CD and other basic repo and + build files can be used. +- Onboarding for contributors is easier if they come from the open + source community. +- Open source projects very often follow this approach, so its easier + to draw inspiration and learn how other projects do things. +- Using version control, managing the commit history, and working with + pull requests can be easier, since they will be specific to the + project. **Cons:** -- Creating another project requires time and setup. -- Project management at a organization level is a bit more challenging, since there are now multiple repos to manage rather than one. -- Onboarding of team members can be more tricky because there are now many repos to consider and keep mental track of then before. -- When something changes in one repo, managing its impact on other repos might be tricky, if strict de-coupling is not managed well and architectural designs aren't followed or developed soon enough. +- Creating another project requires time and setup. +- Project management at a organization level is a bit more + challenging, since there are now multiple repos to manage rather + than one. +- Onboarding of team members can be more tricky because there are now + many repos to consider and keep mental track of then before. +- When something changes in one repo, managing its impact on other + repos might be tricky, if strict de-coupling is not managed well and + architectural designs aren't followed or developed soon enough. ### Hybrid -In general, whether you decide on following a mono-repo or poly-repo approach, there is *always* some level of mono- or poly- structure in the codebase. It is a bit of a spectrum and no project is truly at either end. However, explicitly deciding on a hybrid approach doesn't seem like there are any benefits. +In general, whether you decide on following a mono-repo or poly-repo +approach, there is *always* some level of mono- or poly- structure in +the codebase. It is a bit of a spectrum and no project is truly at +either end. However, explicitly deciding on a hybrid approach doesn't +seem like there are any benefits. -## Decision Outcome +## Decision outcome -Ultimately, we decided on using a poly-repo approach because we'll need to build workflows and processes for developing multiple repositories simultaneously anyway, in addition to the easier project-level management and ability for users to install individual components as well. It also works well for our ideal team workflow of working on individual projects in rotations. +Ultimately, we decided on using a poly-repo approach because we'll need +to build workflows and processes for developing multiple repositories +simultaneously anyway, in addition to the easier project-level +management and ability for users to install individual components as +well. It also works well for our ideal team workflow of working on +individual projects in rotations. ### Consequences -- Means we will need to develop templates for different project types (website, Python Package, R Package, Django App). -- We'll need to connect and synch common files across projects. -- We'll have to learn and apply team-based workflows around using this approach. +- Means we will need to develop templates for different project types + (website, Python Package, R Package, Django App). +- We'll need to connect and synch common files across projects. +- We'll have to learn and apply team-based workflows around using this + approach. diff --git a/why-postgres.qmd b/why-postgres.qmd index 54af787..b601e89 100644 --- a/why-postgres.qmd +++ b/why-postgres.qmd @@ -4,8 +4,7 @@ description: | SQL is the backbone of any database system. However there are many variants of SQL. This decision post contains the reasons for using PostgreSQL, which is a powerful and feature-full variant of SQL. -author: Kristiane Beicher -date: last-modified +date: "2024-01-05" categories: - backend - database @@ -15,114 +14,178 @@ categories: - software-architecture --- -## Context and Problem Statement +## Context and problem statement -Building databases are best done through by using formal database systems. Most scientific research makes use of or uses databases that are relational rather than unstructured, and we believe that the user base for Seedcase will likely want or be familiar with a relational database structure. The type of database systems that are relational are called Structured Query Language ([SQL](https://en.wikipedia.org/wiki/SQL)). There are a large number of different SQL variants available, so we need to decide which one to use. +Building databases are best done through by using formal database +systems. Most scientific research makes use of or uses databases that +are relational rather than unstructured, and we believe that the user +base for Seedcase software will likely want or be familiar with a +relational database structure. The type of database systems that are +relational are called Structured Query Language +([SQL](https://en.wikipedia.org/wiki/SQL)). There are a large number of +different SQL variants available, so we need to decide which one to use. -We're only look at the top three open source relational databases (as defined by [DB-Engines](https://db-engines.com/en/ranking/relational+dbms) in November 2022): MySQL, PostgreSQL, and SQLite. +We're only look at the top three open source relational databases (as +defined by +[DB-Engines](https://db-engines.com/en/ranking/relational+dbms) in +November 2022): MySQL, PostgreSQL, and SQLite. -As we are planning to use [container technology](why-containers.qmd) to run the database it is not as important which operating systems the database will run on. Having said that, of the three systems that we are looking at, MySQL and PostgreSQL will run on multiple operating systems (e.g. Linux, Mac OS, and Windows), and SQLite is a classic serverless application. +As we are planning to use [container technology](why-containers.qmd) to +run the database it is not as important which operating systems the +database will run on. Having said that, of the three systems that we are +looking at, MySQL and PostgreSQL will run on multiple operating systems +(e.g. Linux, Mac OS, and Windows), and SQLite is a classic serverless +application. -A [side-by-side comparison](https://db-engines.com/en/system/MySQL%3BPostgreSQL%3BSQLite) -on [DB-Engines](https://db-engines.com) was used to compile some of the comparison below. +A [side-by-side +comparison](https://db-engines.com/en/system/MySQL%3BPostgreSQL%3BSQLite) +on [DB-Engines](https://db-engines.com) was used to compile some of the +comparison below. -## Decision Drivers +## Decision drivers -One of the most important functions of Seedcase is to handle data, and the most efficient and flexible ways of doing this is to store it in a database. We need a SQL database system that fits our needs best. +One of the most important functions of Seedcase software is to handle +data, and the most efficient and flexible ways of doing this is to store +it in a database. We need a SQL database system that fits our needs +best. -## Considered Options +## Considered options ### MySQL -[MySQL](www.mysql.com) was first released in 1995 and is maintained by Oracle Corp. It is an open source platform with the option to deploy either as a local server solution or cloud based. The implementation languages are C and C++, and it runs of a variety of operating systems. The system allows access through standard technologies (ADO.NET, JDBC, ODBC, and native APIs). +[MySQL](www.mysql.com) was first released in 1995 and is maintained by +Oracle Corp. It is an open source platform with the option to deploy +either as a local server solution or cloud based. The implementation +languages are C and C++, and it runs of a variety of operating systems. +The system allows access through standard technologies (ADO.NET, JDBC, +ODBC, and native APIs). ::: columns -::: {.column style="font-size: 90%"} +::: column +#### Benefits -#### Benefits +- At present the second most popular database both open source and + overall with good support and a large community. -* At present the second most popular database both open source and overall with good support and a large community. +- Traditional database system with a recognisable format which should + be easy to manipulate and work with for the advanced Seedcase user. -* Traditional database system with a recognisable format which should be easy to manipulate and work with for the advanced Seedcase user. - -* Support for both XML and JSON formats, both reading and writing. - -* There are a number of ways for MySQL to interact with Apache Parquet files. +- Support for both XML and JSON formats, both reading and writing. +- There are a number of ways for MySQL to interact with Apache Parquet + files. ::: -::: {.column style="font-size: 90%"} +::: column #### Drawbacks -* MySQL is run by Oracle which is a commercial entity. There is always a risk that the company decides to reverse the open source concept and go move to a solution with a free light version and full payable version. In the case of MySQL, it is very unlikely as the software is very well established and the user user community quite large. - -* There is currently no option in MySQL to store data in a columnar (rather than row-based) table. +- MySQL is run by Oracle which is a commercial entity. There is always + a risk that the company decides to reverse the open source concept + and go move to a solution with a free light version and full payable + version. In the case of MySQL, it is very unlikely as the software + is very well established and the user user community quite large. +- There is currently no option in MySQL to store data in a columnar + (rather than row-based) table. ::: ::: ### PostgreSQL -[PostgreSQL](www.postgresql.org) was first released in 1989 from UC Berkeley and is maintained by the PostgreSQL Development Group. It is an open source platform with the option to deploy either as a local server solution or cloud based. The implementation language is C, and it runs of a variety of operating systems. The system allows access through standard technologies (ADO.NET, JDBC, ODBC, a native C library, and streaming APIs). +[PostgreSQL](www.postgresql.org) was first released in 1989 from UC +Berkeley and is maintained by the PostgreSQL Development Group. It is an +open source platform with the option to deploy either as a local server +solution or cloud based. The implementation language is C, and it runs +of a variety of operating systems. The system allows access through +standard technologies (ADO.NET, JDBC, ODBC, a native C library, and +streaming APIs). ::: columns -::: {.column style="font-size: 90%"} - -#### Benefits - -* At present, it is the fourth most popular database overall, and the second most popular open source database. There is a thriving community with a lot of engaging users delivering support. +::: column +#### Benefits -* Traditional database system with a recognisable format which should be easy to manipulate and work with for the advanced Seedcase user. +- At present, it is the fourth most popular database overall, and the + second most popular open source database. There is a thriving + community with a lot of engaging users delivering support. -* Support for both XML and JSON formats, both reading and writing. +- Traditional database system with a recognisable format which should + be easy to manipulate and work with for the advanced Seedcase user. -* There are scripts that will allow for PostgreSQL to interact with Apache Parquet files. +- Support for both XML and JSON formats, both reading and writing. -* It is possible to create columnar based tables directly in PostgreSQL. +- There are scripts that will allow for PostgreSQL to interact with + Apache Parquet files. +- It is possible to create columnar based tables directly in + PostgreSQL. ::: -::: {.column style="font-size: 90%"} +::: column #### Drawbacks -* We don't see any major drawbacks. - +- We don't see any major drawbacks. ::: ::: ### SQLite -First released in 2000, SQLite is slightly different to the two systems described above, as it is an embedded serverless database primarily maintained by an international team of programmers (see [About SQLite](https://www.sqlite.org/about.html)). It is an open source platform with the option to deploy either locally or in the cloud. The implementation language is C, and it is platform independent. The system allows access through standard technologies (ADO.NET, JDBC, and ODBC). +First released in 2000, SQLite is slightly different to the two systems +described above, as it is an embedded serverless database primarily +maintained by an international team of programmers (see [About +SQLite](https://www.sqlite.org/about.html)). It is an open source +platform with the option to deploy either locally or in the cloud. The +implementation language is C, and it is platform independent. The system +allows access through standard technologies (ADO.NET, JDBC, and ODBC). ::: columns -::: {.column style="font-size: 90%"} - -#### Benefits +::: column +#### Benefits -* Support for both XML and JSON formats, both reading and writing. +- Support for both XML and JSON formats, both reading and writing. -* Easy to set up and implement, works well with R and other languages. - -* There is always a risk that an open source community will break apart and leave a product unsupported, but the risk here looks minimal. The explicitly stated intention from the core developers of SQLite is to support the product until at least 2050. +- Easy to set up and implement, works well with R and other languages. +- There is always a risk that an open source community will break + apart and leave a product unsupported, but the risk here looks + minimal. The explicitly stated intention from the core developers of + SQLite is to support the product until at least 2050. ::: -::: {.column style="font-size: 90%"} +::: column #### Drawbacks -* SQLite is not fully ACID (atomicity, consistency, isolation, and durability) compliant, which is always a risk when working with larger data sets. - -* The database is designed primarily as a tool to sit underneath applications running in single user mode. This means that the database does not as a standard support multi-user work. +- SQLite is not fully ACID (atomicity, consistency, isolation, and + durability) compliant, which is always a risk when working with + larger data sets. -* As the database is serverless it is quite possible that the target audience for the Seedcase project will struggle to work with the database in the instances where local development is needed. +- The database is designed primarily as a tool to sit underneath + applications running in single user mode. This means that the + database does not as a standard support multi-user work. +- As the database is serverless it is quite possible that the target + audience for the Seedcase Project will struggle to work with the + database in the instances where local development is needed. ::: ::: -## Decision Outcome +## Decision outcome -We've decided to work with PostgreSQL as our backend database as it fulfills all our needs and is a very popular open source tool. MySQL would be the other obvious choice, the application does everything that Seedcase needs, but the user community for PostgreSQL seems to be a bit more active. SQLite is quite popular within the application developer community, but it doesn't have a reliable multi-user functionality, so it may be an uphill battle to get it to do the things we are hoping to do with Seedcase. +We've decided to work with PostgreSQL as our backend database as it +fulfils all our needs and is a very popular open source tool. MySQL +would be the other obvious choice, the application does everything that +Seedcase software needs, but the user community for PostgreSQL seems to +be a bit more active. SQLite is quite popular within the application +developer community, but it doesn't have a reliable multi-user +functionality, so it may be an uphill battle to get it to do the things +we are hoping to do with Seedcase products. ### Consequences -The main consequence of our choice is the limiting factor in who can work on the project. Anyone wanting to work on the database part will need to have an understanding of for instance [psql](https://www.postgresql.org/docs/current/app-psql.html), which is the command line tool to work with Postgres. There are not many differences between Postgres and the other large database systems, but there is always some differences in the version of SQL they use, and which terms are used. +The main consequence of our choice is the limiting factor in who can +work on the project. Anyone wanting to work on the database part will +need to have an understanding of for instance +[psql](https://www.postgresql.org/docs/current/app-psql.html), which is +the command line tool to work with Postgres. There are not many +differences between Postgres and the other large database systems, but +there is always some differences in the version of SQL they use, and +which terms are used. diff --git a/why-python.qmd b/why-python.qmd index c6a4cb8..b9b6c30 100644 --- a/why-python.qmd +++ b/why-python.qmd @@ -2,59 +2,224 @@ title: "Why Python" description: | Python is one of the most common and widely used programming languages. - It is used across multiple domains and industries, which means more people - would be familiar with using it. -author: "Richard Ding" + As it is used across multiple domains and industries, it is likely to be familiar to a wider audience. date: "2023-03-22" -date-modified: last-modified +date-modified: "2024-05-10" categories: - programming - development - software-architecture --- - +::: content-hidden +Use other decision posts as inspiration to writing these. Leave the +content-hidden sections in the text for future reference. +::: -## Introduction +## Context and problem statement -Since Seedcase is a data management system and software, it requires a -programming language for its development that can handle large amounts -of data, provide efficient data processing capabilities, and integrate -well with other technologies commonly used in the research area. +::: content-hidden +State the context and some background on the issue, then write a +statement in the form of a question for the problem. +::: -## Considered Options +One of the first things to do when deciding to write a software +application is to decide on the programming language. There are several +languages that can be used, among them C++, Java, Python, and R. In the +context of the Seedcase Project it is important to choose a language +that can handle large amounts of data, provide efficient data processing +capabilities, and integrate well with other technologies commonly used +in the research area. -We considered [Python](https://www.python.org), [Java](https://www.java.com/en/), [C++](https://cplusplus.com), and [R](https://www.r-project.org). +> Which programming language should we use for developing Seedcase +> software? -## Decision Outcome +## Decision drivers -We have decided to use Python as the main development language for the -following reasons: +::: content-hidden +List some reasons for why we need to make this decision and what things +have arisen that impact work. +::: -- Is widely used in the research area, particularly in data science - and machine learning, and has a rich ecosystem of libraries and - tools for data processing and analysis. -- It's syntax is concise and easy to read, making it ideal for rapid - development and prototyping. -- Has a large community of developers who contribute to its - development, ensuring that it is constantly evolving and improving. -- Has strong support for web development, with a number of popular - frameworks such as [Django](https://www.djangoproject.com) and [Flask](https://flask.palletsprojects.com/en/2.3.x/), making it easy to build RESTful - APIs for Seedcase. -- Has excellent support for working with databases, with libraries - such as [SQLAlchemy](https://www.sqlalchemy.org) and Django ORM, making it easy to manage and - query large datasets. -- Is a cross-platform language, making it easy to deploy the system on - a variety of operating systems and hardware. +In the context of the Seedcase Project it is important to chose a +language that can handle large amounts of data, provide efficient data +processing capabilities, and integrate well with other technologies +commonly used in the research area. There is also a consideration with +regards to the skills already available in the core team, as we would +like to minimize the amount of time that we will need to use in order to +be able to program the application. -While Java and C++ are also capable languages for building data -management systems, they are generally more complex and have a steeper -learning curve than Python. R is a powerful language for data analysis -and visualization, but it is less suitable for building large-scale web -applications. +## Considered options -## Conclusion +::: content-hidden +List and describe some of the options, as well as some of the benefits +and drawbacks for each option. +::: -Python is the most suitable option for this project, as it provides a -powerful, flexible, and easy-to-use platform for building a data -management system. Python is also one of the most common and widely used programming languages and is used across multiple domains and industries. +### C++ + +::: columns +::: column +#### Benefits + +- Well-suited for real-time and performance-critical applications. +- Allows fine-grained control over memory and hardware resources, + enabling low-level, use-case-specific optimisations. +- Compilation to native machine code for the target platform prior to + execution guarantees better runtime performance than Python and, + potentially by a smaller margin, Java. +- Static type-checking at compile time helps to catch certain types of + bugs early on. +- Mature libraries and frameworks available for web development and + data analysis. +- Active community and extensive resources. +::: + +::: column +#### Drawbacks + +- Compilation to native machine code makes C++ programs more platform + dependent, broadly speaking, than programs in interpreted languages. +- Use of platform-specific language features or libraries can lead to + portability issues. +- Lack of automatic garbage collection means that developers need more + awareness of how memory is managed in the application. +- Offer of database management libraries is more limited than for Java + or Python. +- Syntax is verbose and less close to natural language, making + development less rapid. +- No inline documentation generation system out of the box. +- Less widespread in academic and research communities. +- Has a steep learning curve, arguably steeper than Java's. +::: +::: + +### Java + +::: columns +::: column +#### Benefits + +- Code is run on a Java Virtual Machine, making Java programs, + generally, platform independent (provided the host has a Java + Runtime Environment installed). +- Better runtime performance than Python. +- Static type-checking at compile time helps to catch certain types of + bugs early on. +- Comes with inline documentation generation system out of the box + (Javadoc). +- Large ecosystem of mature libraries and frameworks for web + development and database management. +- Active community and extensive resources. +::: + +::: column +#### Drawbacks + +- Fewer libraries for data analysis than Python. +- Syntax is verbose and less close to natural language, making + development less rapid. +- Less widespread in academic and research communities. +- Has a steeper learning curve than Python, especially for people with + little programming experience. +::: +::: + +### Python + +::: columns +::: column +#### Benefits + +- Code is executed by a Python interpreter, making Python programs + platform independent (provided the host has an interpreter + installed). +- Concise, easy-to-read, beginner-friendly syntax. +- Easy to iterate and prototype rapidly. +- Large ecosystem of mature libraries and frameworks for web + development (e.g. [Django](https://www.djangoproject.com), + [Flask](https://flask.palletsprojects.com/en/2.3.x/)), database + management (e.g. [SQLAlchemy](https://www.sqlalchemy.org), Django's + Object Relational Mapper), and data analysis. +- Active community and extensive resources. +- Very popular in data-intensive research and academia, some target + users of Seedcase are likely to be familiar with Python. +::: + +::: column +#### Drawbacks + +- Worse runtime performance than Java or C++, partly because the + interpreter does less pre-execution optimisation and instead follows + the layout of the source coded sequentially during program + execution. +- Dynamic type-checking at runtime can make it more difficult to catch + certain types of bugs early on. +::: +::: + +### R + +::: columns +::: column +#### Benefits + +- Designed for statistical computing with excellent data visualisation + capabilities. +- Wide array of packages for data analysis. +- Active community and extensive resources. +- Very popular in data-intensive research and academia, some target + users of Seedcase are likely to be familiar with R. +::: + +::: column +#### Drawbacks + +- Less versatile and general purpose than the other languages + considered. +- While there is a web application framework for R + ([Shiny](https://shiny.posit.co/)), this is intended primarily for + interactive data visualisation, and offers more limited features + than the frameworks for the other languages considered. +::: +::: + +## Decision outcome + +::: content-hidden +What decision was made, use the form "We decided on CHOICE because of +REASONS." +::: + +We have decided to use Python as the main development language for +Seedcase software because it is a powerful, flexible and easy-to-use +platform for building a data management web application. Drawing on the +skills of the core Seedcase team, Python offers the best balance of +capabilities and ease of development out of the options considered. It +is, moreover, a language likely to be familiar to +technologically-oriented Seedcase users and prospective contributors. + +While Java and C++ offer more scope for context-specific performance +optimisation, we are unlikely to need this level of control for Seedcase +software, because the number of concurrent user requests is expected to +be low, resource-intensive backend tasks are expected to run without +much competition, and we don't expect to do heavy-duty, real-time data +analysis or image processing. Therefore, for our use case, the +advantages of these languages don't justify their steeper learning curve +and added complexity. + +We decided not to use R because, while it is a powerful language for +data analysis and visualization, it is less suitable for building +large-scale web applications. + +### Consequences + +::: content-hidden +List some potential consequences of this decision. +::: + +If further on we run into performance issues, we will need to look into +performance improvement strategies, such as optimising our algorithms, +our database queries and organisation, and how much data is loaded into +program memory at once. However, these are considerations that inform +everyday development decisions in any case. diff --git a/why-quarto.qmd b/why-quarto.qmd index 0218194..c39032d 100644 --- a/why-quarto.qmd +++ b/why-quarto.qmd @@ -1,21 +1,48 @@ --- title: "Why Quarto" description: "Our reasons for using Quarto to build the website and write the general documentation." -author: "Luke W. Johnston" -date: last-modified +date: "2023-06-25" categories: - documentation - markdown - website --- - +::: content-hidden +Use other decision posts as inspiration to writing these. Leave the +content-hidden sections in the text for future reference. +::: + +## Context and problem statement + +::: content-hidden +State the context and some background on the issue, then write a +statement in the form of a question for the problem. +::: + +A software project like Seedcase needs an easy way to communicate and +share knowledge for those internal and external to Seedcase (including +users and contributors), the most common way being to put these content +(like documentation) on a website. In order to minimize the work the +team needs to do, we would like to use the files we maintain in GitHub +as the basis for a public website. The question then becomes: + +> How do we build a website based on the files in GitHub with minimal +> amount of overhead and that can be integrated into GitHub in some way? + +## Decision drivers + +::: content-hidden +List some reasons for why we need to make this decision and what things +have arisen that impact work. +::: There are many different types of "static website generators"[^1], like [Jekyll](https://jekyllrb.com/) or [Hugo](https://gohugo.io/). They all have their pros and cons, and we ultimately have to choose one to use when writing content for this website and to build it, as well as when -writing the documentation for Seedcase itself. +writing the documentation for Seedcase software itself. We have the +following needs when it comes to this decision: [^1]: A static website or blog generator is a framework for building websites based on pure, plain HTML files (unlike building websites @@ -23,29 +50,155 @@ writing the documentation for Seedcase itself. meaning it is a simple file that is being shown by the browser as a webpage. +- Is generally programming language agnostic (e.g. doesn't need + knowledge of the language to build or manage). +- Powerful enough to have some customizations with structure and + organization of websites. +- Good, beginner-friendly documentation on how to use the tool. +- Relatively easy theming and aesthetic customization. +- Uses Markdown as the basis for writing content (see [Why + Markdown](why-markdown.qmd) for reasons on why). + +## Considered options + +::: content-hidden +List and describe some of the options, as well as some of the benefits +and drawbacks for each option. +::: + +Based on the needs listed above, only a few tools are capable of meeting +these needs. Resources like [Jamstack](https://jamstack.org/generators/) +and [Awesome Static +Generators](https://github.com/myles/awesome-static-generators) provided +a list of potential static site generators that we could use to build +websites. The ones we compared are: + +- [mdBook](https://rust-lang.github.io/mdBook/index.html) +- [MkDocs](https://www.mkdocs.org/) +- [Quarto](https://quarto.org/) + +### mdBook + +[mdBook](https://rust-lang.github.io/mdBook/index.html) is a fairly +recent tool that is built with Rust and is a very lightweight and simple +static site generator. It is mainly used for writing books and +documentation and includes some basic website features. + +::: columns +::: column +#### Benefits + +- Can build websites very quickly because it is built with Rust. +- Simple and clean website design. +::: + +::: column +#### Drawbacks + +- While it isn't required to know Rust, it is developed with using + Rust in mind. For example, you can test if Rust code snippets + compile correctly. +- There is a good amount of technical knowledge and overhead needed to + setup and build the website, for instance, there are at least 5 + commands required for using the tool. +- Adding extensions and customizing the website requires some + knowledge and learning to use, and there aren't many default or + built-in themes to choose from. +- Uses [CommonMark](https://commonmark.org/) as the Markdown + specification, which isn't as powerful or feature-filled as other + Markdown flavors like [Pandoc + Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown) (which + builds on CommonMark). +- Main focus is on writing books and documentation, not general + websites. +::: +::: + +### MkDocs + +[MkDocs](https://www.mkdocs.org/) is an established and widely used tool +that is built with Python and installable through `pip`. It is a simple +and fast website generator. + +::: columns +::: column +#### Benefits + +- Very simple and easy to use, with a lot of documentation and + tutorials available. +- Very popular tool, especially within the Python community. +- Beginner-friendly documentation. +::: + +::: column +#### Drawbacks + +- Assumes and encourages placing content in the `docs` folder, which + might not be the best way to organize content for some websites. +- Setting up custom themes and extensions requires some work. +- Is based on the original Markdown specification, which is fairly + basic and has since evolved into more powerful and feature-rich + versions like [Pandoc + Markdown](https://pandoc.org/MANUAL.html#pandocs-markdown). +- While it is generally straight forward to use, features and layouts + as well as extensibility and customization are limited. +::: +::: + +### Quarto + Within the R world, a recent new tool came out called -[Quarto](https://quarto.org/). Since its release, it has completely -taken over as the tool to use when working with R and data science. We -will use this tool because it aligns with our [values and philosophies](https://seedcase-project.org/about.html#principles) -for multiple reasons. - -1. It is open source. -2. The documentation is phenomenal and very beginner friendly. -3. It is sponsored by an organization ([Posit](https://posit.co/)) with +[Quarto](https://quarto.org/). While new, since its release, it has +gained enormous popularity as a language-agnostic tool for writing +books, documentation, and websites, especially within the data science +community. + +::: columns +::: column +#### Benefits + +- The documentation is fantastic and very friendly to beginners. +- It is sponsored by an organization ([Posit](https://posit.co/)) with an established history of supporting and contributing to open source projects. -4. The software design is extremely well developed and structured, +- The software design is extremely well developed and structured, which makes it easier to use compared to other alternatives. -5. It has multi-language support (like R and Python), but is itself +- It has multi-language support (like R and Python), but is itself language-agnostic. -6. Because it is integrated into RStudio, many data scientists and - researchers who use R will quickly become familiar with it. -7. It has support for integration with other applications, like [VS +- It has support for integration with other applications, like [VS Code](https://code.visualstudio.com/), which is also used by many software developers and data scientists. -8. It is built on top of [Pandoc Markdown](https://pandoc.org/), which +- It is built on top of [Pandoc Markdown](https://pandoc.org/), which the de facto standard for writing Markdown, with strong historical use and community support. +- It has a large number of built-in functionality and features, while + still being easy to use. +- It is very easy to customize and extend the website to fit ones + needs, with themes and plugins that are easy to develop and install. +::: + +::: column +#### Drawbacks + +- It is a relatively new tool, so there will be some bugs and issues + that come up along the way. +- Isn't as fast to build as other tools, like mdBook. +- While not necessary for most purposes, developing certain features + when making a Quarto extension requires some knowledge of + [Lua](https://www.lua.org). +::: +::: + +## Decision outcome + +::: content-hidden +What decision was made, use the form "We decided on CHOICE because of +REASONS." +::: -For these reasons, we write our documentation that includes the website -with Quarto. +We have decided to go with Quarto as this seems to be the most +accessible, as well as being a tool that there is already support for +internally in the team. It has the most functionality when it comes to +features, theming, and customization, while still being very easy to use +if you have very basic knowledge of Pandoc Markdown, building websites, +and file paths. diff --git a/why-ruff.qmd b/why-ruff.qmd index 217beeb..29a822d 100644 --- a/why-ruff.qmd +++ b/why-ruff.qmd @@ -4,10 +4,7 @@ description: | Enforcing style of code with automatic linters and formatters is important for code reviews to focus on content, not style. This post covers the reasons why we decided on Ruff for our linting and formatting purposes. -author: - - "Richard Ding" - - "Luke Johnston" -date: 2023-11-27 +date: "2023-11-27" categories: - contributing - culture @@ -22,23 +19,23 @@ categories: - workflow --- -## Context and Problem Statement +## Context and problem statement -Humans are prone to error when writing, whether it is code or text. In a team setting, more people working on the same things increase the chance of more issues occuring. And writing code is not done for the computer, but for other humans to read, so readability and consistency in style become important when reviewing that code. So our problem is: +Humans are prone to error when writing, whether it is code or text. In a team setting, more people working on the same things increase the chance of more issues occurring. And writing code is not done for the computer, but for other humans to read, so readability and consistency in style become important when reviewing that code. So our problem is: > How do we enforce a consistent style across people and code? And how do we catch simple errors that happen because of the style or format of the code? -## Decision Drivers +## Decision drivers - We want to review content and logical of code, not code style. - We want an automated way of fixing simple typographical errors and issues. - We want an automated way of enforcing a standard style. -## Considered Options +## Considered options The terms "linting" or "formatting" are used to describe scanning, analysing, and (potentially) fixing code for style and typographical issues. The important difference between linting and formatting is that linting only tells you about the issues while formatting will fix (many of) the issues. Some issues can't be solved from formatting alone, so both linting and formatting are often used together. -There are many tools available for Python, with many websites that have detailed comparisons of them (like [this](https://realpython.com/python-code-quality/), [this](https://geekflare.com/python-linter-platforms/), or [this](https://github.com/caramelomartins/awesome-linters#python) website). Based on this list and based on quick searchs on Google, these are the tools that come up the most often: +There are many tools available for Python, with many websites that have detailed comparisons of them (like [this](https://realpython.com/python-code-quality/), [this](https://geekflare.com/python-linter-platforms/), or [this](https://github.com/caramelomartins/awesome-linters#python) website). Based on this list and based on quick searches on Google, these are the tools that come up the most often: - [Pylint](https://github.com/pylint-dev/pylint) - [Flake8](https://github.com/PyCQA/flake8) @@ -49,45 +46,72 @@ Below is a detailed description of the pros and cons based on what others have w ### Pylint -- Pros: +::: {.columns} +::: {.column} +#### Benefits + - Very old, well-established linter - Large community of users and contributors - Very comprehensive list of checks - Highly configurable - Is integrated into many other tools (like flake8, black, and ruff) - Linting feedback is extensive -- Cons: - - Too much configuration needed. - - Slow to run. - - Is often not needed to use on it's own because it is integrated with other tools. - - Linting feedback is extensive and a bit overwhelming. +::: +::: {.column} +#### Drawbacks + + - Too much configuration needed + - Slow to run + - Is often not needed to use on it's own because it is integrated with other tools + - Linting feedback is extensive and a bit overwhelming +::: +::: ### Flake8 -- Pros: +::: {.columns} +::: {.column} +#### Benefits + - Extensive list of checks - Includes many other linters - Often used with formatters like Black - Customizable - - Large userbase and community + - Large user base and community - Can use plugins to expand functionality -- Cons: +::: +::: {.column} +#### Drawbacks + - Only lints and doesn't format - Is integrated into newer tools (like Ruff), so might not need to be used on it's own +::: +::: ### Black -- Pros: - - Is a code formatter, not linter. - - Opinionated set of rules for code formatting, so removes need to configure things. +::: {.columns} +::: {.column} +#### Benefits + + - Is a code formatter, not linter + - Opinionated set of rules for code formatting, so removes need to configure things - Recommend to use with a linter (often suggested to use flake8 or pylint) -- Cons: +::: +::: {.column} +#### Drawbacks + - Difficult to configure customizations - Integrated/compatible with newer tools (like Ruff) +::: +::: ### Ruff -- Pros: +::: {.columns} +::: {.column} +#### Benefits + - Very fast - Implements almost all of Black and flake8 features - Implements many other features from other code analysis and checking tools @@ -95,15 +119,20 @@ Below is a detailed description of the pros and cons based on what others have w - Newer and has more modern development - Configuration is available and relatively straightforward to use - Can be implemented alongside other tools -- Cons: +::: +::: {.column} +#### Drawbacks + - Is still new, so bugs and other features are still being developed - Does not yet have all of pylint features implemented +::: +::: -## Decision Outcome +## Decision outcome We decided on Ruff because it is a newer tool that implements many of the other tools that exist. It also is designed to be mostly used "as is", without needing to customize many things. It is also seems to be design in a way that makes customizations relatively easy to set up. -## Potential Consequences +## Potential consequences -- We might miss out on some features from pylint (since right now we won't include pylint). -- There may be some bugs along the way because Ruff is relatively new, though this can be minimized by relying on more stable versions of it. +- We might miss out on some features from pylint (since right now we won't include pylint) +- There may be some bugs along the way because Ruff is relatively new, though this can be minimized by relying on more stable versions of it diff --git a/why-semver.qmd b/why-semver.qmd new file mode 100644 index 0000000..a5cdb62 --- /dev/null +++ b/why-semver.qmd @@ -0,0 +1,178 @@ +--- +title: "Why choose Semantic Versioning (SemVer) for software" +description: "Our reasons for using SemVer for versioning the releases of our software projects." +date: "2024-05-24" +categories: +- development +- management +- organization +- versioning +--- + +::: content-hidden +Use other decision posts as inspiration to writing these. Leave the +content-hidden sections in the text for future reference. +::: + +## Context and problem statement + +::: content-hidden +State the context and some background on the issue, then write a +statement in the form of a question for the problem. +::: + +Since our core aim for the Seedcase Project is building software, we +need some way of communicating changes made to our software whenever we +release an update. [Software +versioning](https://en.wikipedia.org/wiki/Software_versioning) is an +approach to communicating changes in a software whenever a new "version" +or update is released that is widely used throughout the software +industry, almost for as long as software as been built. But there are +different ways to version software, so the question is: + +> Which style of software versioning do we use for our software +> projects? + +## Decision drivers + +::: content-hidden +List some reasons for why we need to make this decision and what things +have arisen that impact work. +::: + +Like any software project, we need some way to communicate with +ourselves, with contributors, with users who are developers, and with +our non-technical users, what version of our software is installed. This +is necessary to deal with bug reports, identifying issues that come up, +and to communicate breaking changes, the addition of new features, or +that bugs have been fixed. This type of communication and information is +handled through the software version as well as the changelog that is +based on the version. + +Having versions also helps us in developing and deploying our software +as we build and test things out. + +## Considered options + +::: content-hidden +List and describe some of the options, as well as some of the benefits +and drawbacks for each option. +::: + +There are two major software versioning systems: semantic versioning, +which bases the version on what was changed between releases, and +calendar versioning, which bases the version on when the release was +made. Broadly, each style has variations, which sometimes can be a +combination of the two. We'll compare the two most common, standardised +systems: + +- [Semantic Versioning (SemVer)](https://semver.org/) +- [Calendar Versioning (CalVer)](https://calver.org/) + +### SemVer + +SemVar is a versioning system that uses a three-part version number: +`MAJOR.MINOR.PATCH`. This system is widely used in the software industry +and is well understood by developers. For instance, with a bug fix, +`PATCH` is incremented by 1, going from `0.0.0` to `0.0.1`. For `MINOR`, +you increment by 1 when there is a new feature, so from `0.0.1` to +`0.1.0`. For `MAJOR`, you increment by 1 when there is a breaking +change, so from `0.1.0` to `1.0.0`. + +::: columns +::: column +#### Benefits + +- This is the most widely used versioning system in the software + industry, so it's familiar to most people in the industry. +- It conveys information about changes well, since it's clear from the + numbering what has changed between versions +- It has a large number of tools and packages that support it, combine + well with it, or integrate well into development workflows around + it. For instance, tools like: + - [Conventional + Changelog](https://github.com/conventional-changelog/conventional-changelog) + to automatically generate changelogs based on the commit + messages that use the [Conventional + Commits](why-conventional-commits.qmd) format. + - [Python Semantic + Release](https://python-semantic-release.readthedocs.io/en/latest/) + to automatically increment the version number based on the + changes made and create a release based on changes to the + version. +::: + +::: column +#### Drawbacks + +- It can be very difficult to determine when something is a major, + minor, or patch change. Sometimes it is perfectly clear, but often, + a change is hard to place in these three categories. +- It can be difficult to determine what constitutes a breaking change. +- More difficult (but not impossible) to automate, since it can + involve a large amount of human judgement. +::: +::: + +### CalVer + +CalVer is a system that is based on dates. Unlike SemVer, there are more +variations available to use, for instance, `YYYY.MM` or `YY.MM`. Also +unlike SemVer, there are more often variations that combine features of +SemVer and CalVer, such as `YYYY.MINOR.PATCH`. + +::: columns +::: column +#### Benefits + +- Very easy to use and understand, as it is based on dates. Whatever + date the software is released on is the version number. +- Works very well for some software projects, especially those with + very regular releases. For instance, the most popular Linux + distribution, Ubuntu, uses a form of CalVer, that increment every 6 + months. +::: + +::: column +#### Drawbacks + +- It doesn't contain any information on what was changed between + versions. +- Breaking changes are not communicated in the version number. +- There are substantially fewer tools and packages to help automate + release and development workflows compared to SemVer. +- Doesn't work as well for some software projects, especially those + that are not released on a regular basis. +::: +::: + +## Decision outcome + +::: content-hidden +What decision was made, use the form "We decided on CHOICE because of +REASONS." +::: + +We decided to use Semantic Versioning (SemVar) for versioning our +software. While it can be more difficult to implement as it may require +some human judgement to decide on which version to increment based on +the changes made, because it is so widely used, the availability of +tools that support it or exclusively depend on it is very large. It will +ultimately make it easier for us during development because we can make +use of those existing tools to handle tasks like version release and +changelog generation for us. + +### Consequences + +::: content-hidden +List some potential consequences of this decision. +::: + +One of the biggest consequences of using SemVer is that it does take a +bit of effort to implement the tools that will eventually automate many +of our tasks for us. + +There will also be some variation in how individual team members and +contributors label changes, since there is some level of human judgement +on categorising changes into the correct version number. This will +involve some learning for the team. diff --git a/why-standard-shortcuts.qmd b/why-standard-shortcuts.qmd index 2bd3f39..d327d09 100644 --- a/why-standard-shortcuts.qmd +++ b/why-standard-shortcuts.qmd @@ -1,8 +1,7 @@ --- title: "Why standardized snippets" description: "The larger a project is, the more important it becomes to have a joint set of standards when writing documentation. We decided to set up shortcuts that are shared across the team, so that all documentation follows the same classification and formatting." -author: "Kristiane Beicher" -date: last-modified +date: "2023-11-23" categories: - code snippets - communication @@ -17,62 +16,110 @@ categories: - workflow --- -## Context and Problem Statement +## Context and problem statement -The more documentation we create for Seedcase, the more important it becomes to ensure a smooth reader experience, both in terms of consistency between authors, and in terms of managing the keywords. +The more documentation we create for the Seedcase Project, the more +important it becomes to ensure a smooth reader experience, both in terms +of consistency between authors, and in terms of managing the keywords. -> How do we ensure a uniform layout, an easier to creating documentation, and a usable set of keywords as the documentation for Seedcase grows? +> How do we ensure a uniform layout, an easier to creating +> documentation, and a usable set of keywords as the documentation for +> the Seedcase Project grows? -## Decision Drivers +## Decision drivers -As the documentation for Seedcase growing, and we have reached a level where it is impossible for one person to keep an overview and ensure a consistent layout of the pages. To help with this there are a few tools that can standardise how we write the documentation. [Quarto](why-quarto.qmd) can help with quite a few things (like consistent layout of links and keywords), but it could also be of benefit to us as a team, if it is easy to use the same layout for things like tables and hidden comments. +As the documentation for the Seedcase Project grows, we are likely to +reach a level where it is impossible for one person to keep an overview +and ensure a consistent layout of the pages. To help with this there are +a few tools that can standardise how we write the documentation. +[Quarto](why-quarto.qmd) can help with quite a few things (like +consistent layout of links and keywords), but it could also be of +benefit to us as a team, if it is easy to use the same layout for things +like tables and hidden comments. -We also need to find a way to ensure the consistent use of keywords, so that when a reader clicks a `tag` in a document they get all relevant pages, and don't miss any due to the fact that half are tagged in one way (eg. `database`) and the other half is tagged slightly differently (eg `databases`). +We also need to find a way to ensure the consistent use of keywords, so +that when a reader clicks a `tag` in a document they get all relevant +pages, and don't miss any due to the fact that half are tagged in one +way (eg. `database`) and the other half is tagged slightly differently +(eg `databases`). - +## Considered options -## Considered Options - -We have so far looked at two ways of streamlining the writing of documentation through the use of code snippets and shared keywords, which can be set using the same settings file. There aren't many "generic" methods to share code snippets across IDE's (e.g. between RStudio or PyCharm), so we only investigated ways of adding these in VS Code. +We have so far looked at two ways of streamlining the writing of +documentation through the use of code snippets and shared keywords, +which can be set using the same settings file. There aren't many +"generic" methods to share code snippets across IDE's (e.g. between +RStudio or PyCharm), so we only investigated ways of adding these in VS +Code. ### Code snippets in Quarto markdown files (`.qmd`) -It is possible to set up and share code snippets for `.qmd` files using VS Code and GitHub allowing a team to share for instance formatting code, something that can greatly benefit documentation in particular. These can be added as a file (`.code-snippets`) in the `.vscode` folder for VS Code to find it. Since this a file, we can share it with the team through Git. In the case of Quarto code snippets, the setting file name would be called `quarto.code-snippets`. +It is possible to set up and share code snippets for `.qmd` files using +VS Code and GitHub allowing a team to share for instance formatting +code, something that can greatly benefit documentation in particular. +These can be added as a file (`.code-snippets`) in the `.vscode` folder +for VS Code to find it. Since this a file, we can share it with the team +through Git. In the case of Quarto code snippets, the setting file name +would be called `quarto.code-snippets`. #### Layout of the code-snippet file -Code snippets in this file are written as a JSON structure. Because the file extension is `.code-snippets` the file itself will ignore a couple of JSON file requirements. The main one being that there shouldn't be any comments (denoted by `//`) in the file itself, as well as some requirements to keep sections separated with commas. +Code snippets in this file are written as a JSON structure. Because the +file extension is `.code-snippets` the file itself will ignore a couple +of JSON file requirements. The main one being that there shouldn't be +any comments (denoted by `//`) in the file itself, as well as some +requirements to keep sections separated with commas. An example of the code used to insert a hidden comment is given below. ``` json - "Insert a hidden comment section":{ - "prefix": "hidden", - "body": [ - "::: content-hidden" - "${0:Write comments here}" - ":::" - ], - "description": "Insert a hidden content section" - } + "Insert a hidden comment section":{ + "prefix": "hidden", + "body": [ + "::: content-hidden" + "${0:Write comments here}" + ":::" + ], + "description": "Insert a hidden content section" + } ``` -As can be seen above there are some characters that are 'reserved' when writing the body. The one that will probably most frequently be an issue is the quotation mark `"`, if used in the body it should be prefixed with a backslash `\`, which here acts like an escape character. +As can be seen above there are some characters that are 'reserved' when +writing the body. The one that will probably most frequently be an issue +is the quotation mark `"`, if used in the body it should be prefixed +with a backslash `\`, which here acts like an escape character. ### Shared keywords for documentation files -We want to standardise keywords used in the `categories:` tag of posts to be consistent in both spelling and tenses. It is important for usability of the website that the words used are the same, and spelled the same, so that if a person is looking for how Seedcase handles databases they get everything by clicking on the keyword "database", and aren't missing half the documents because they are tagged with the key word "databases". +We want to standardise keywords used in the `categories:` tag of posts +to be consistent in both spelling and tenses. It is important for +usability of the website that the words used are the same, and spelled +the same, so that if a person is looking for how Seedcase software +handles databases they get everything by clicking on the keyword +"database", and aren't missing half the documents because they are +tagged with the key word "databases". The following guidelines for selecting key words apply: -* **Form** we prefer using nouns over verbs (eg. "documentation" over "documenting", "contribution" over "contributing") -* **Plural vs Singular** we prefer singular over plural (eg. "database" over "databases", and "container" over "containers") -* **More than one word** we prefer to write keywords that consist of more than one word without hyphens (eg. "design architecture" over "design-architecture"), the exception is of course where the word is normally spelled with a hyphen (eg. "back-end") +- **Form** we prefer using nouns over verbs (eg. "documentation" over + "documenting", "contribution" over "contributing") +- **Plural vs Singular** we prefer singular over plural (eg. + "database" over "databases", and "container" over "containers") +- **More than one word** we prefer to write keywords that consist of + more than one word without hyphens (eg. "design architecture" over + "design-architecture"), the exception is of course where the word is + normally spelled with a hyphen (eg. "back-end") #### Implementation -It seems the best way to implement this shared set of keywords is through the code snippets file. +It seems the best way to implement this shared set of keywords is +through the code snippets file. -## Decision Outcome +## Decision outcome -We have decided that we would create and use a set of common code snippets, with the list of keywords for the `categories:` YAML metadata included as a snippet, because that would make it easier for us to write documentation consistently. We will be looking at other editors at a later date, but for now this is the tool used by most of the team, and thus a good place to start. +We have decided that we would create and use a set of common code +snippets, with the list of keywords for the `categories:` YAML metadata +included as a snippet, because that would make it easier for us to write +documentation consistently. We will be looking at other editors at a +later date, but for now this is the tool used by most of the team, and +thus a good place to start.