From ed35d567bba6539970cd61f8facddfa905701633 Mon Sep 17 00:00:00 2001 From: Kris Beicher <112945740+K-Beicher@users.noreply.github.com> Date: Wed, 8 May 2024 14:51:53 +0200 Subject: [PATCH 01/60] docs: complete update to why REST --- why-REST.qmd | 156 ++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 118 insertions(+), 38 deletions(-) diff --git a/why-REST.qmd b/why-REST.qmd index ff6676e..ab1d678 100644 --- a/why-REST.qmd +++ b/why-REST.qmd @@ -2,71 +2,151 @@ 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 --- + - +::: 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 + +::: 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. There -are several design styles available for building APIs, including Representational State Transfer (REST), Simple Object Access Protocol (SOAP), and GraphQL. +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: -## Decision +> Which API technology will best serve the needs of the Seedcase +> project? -We will use the REST architectural style for implementing the communication -protocol between our client and server components, instead of SOAP or -GraphQL. +## Decision Drivers -## Alternatives +::: content-hidden +List some reasons for why we need to make this decision and what things +have arisen that impact work. +::: -### 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. +## Considered Options -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. +::: content-hidden +List and describe some of the options, as well as some of the benefits +and drawbacks for each option. +::: -### GraphQL +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. -[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. +### REST -## Reasons for the decision + -These are the reasons we are deciding on REST: +::: columns +::: column +#### Benefits - Is lightweight and easy to implement, making it a popular choice for - web-based applications. + web-based applications - Uses a simple and intuitive set of HTTP methods, which makes it easy - for developers to understand and use. + 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. + 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. + the requested data - Is often simpler to implement and offers better caching mechanisms. -- Has better tooling support and is more widely adopted. +- 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." +::: -## 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 +make it a better choice for the client-server communication needs of +Seedcase. + +### Consequences + +::: content-hidden +List some potential consequences of this decision. +::: \ No newline at end of file From d1efe54684967eccab3135face9d07a363cea147 Mon Sep 17 00:00:00 2001 From: Kris Beicher <112945740+K-Beicher@users.noreply.github.com> Date: Wed, 8 May 2024 15:02:18 +0200 Subject: [PATCH 02/60] docs: format sub-set of files to comply with template-3 this is the branch containing the python file changes --- why-postgres.qmd | 17 +++-- why-python.qmd | 135 +++++++++++++++++++++++++++---------- why-ruff.qmd | 75 ++++++++++++++------- why-standard-shortcuts.qmd | 5 +- why-text-based.qmd | 6 +- 5 files changed, 161 insertions(+), 77 deletions(-) diff --git a/why-postgres.qmd b/why-postgres.qmd index 54af787..8a8aa0a 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 @@ -37,7 +36,7 @@ One of the most important functions of Seedcase is to handle data, and the most [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 @@ -50,7 +49,7 @@ One of the most important functions of Seedcase is to handle data, and the most * There are a number of ways for MySQL to interact with Apache Parquet files. ::: -::: {.column style="font-size: 90%"} +::: {.column} #### Drawbacks @@ -66,7 +65,7 @@ One of the most important functions of Seedcase is to handle data, and the most [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%"} +::: {.column} #### Benefits @@ -81,7 +80,7 @@ One of the most important functions of Seedcase is to handle data, and the most * It is possible to create columnar based tables directly in PostgreSQL. ::: -::: {.column style="font-size: 90%"} +::: {.column} #### Drawbacks @@ -95,7 +94,7 @@ One of the most important functions of Seedcase is to handle data, and the most 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%"} +::: {.column} #### Benefits @@ -106,7 +105,7 @@ First released in 2000, SQLite is slightly different to the two systems describe * 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 @@ -121,7 +120,7 @@ First released in 2000, SQLite is slightly different to the two systems describe ## 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 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. ### Consequences diff --git a/why-python.qmd b/why-python.qmd index c6a4cb8..9bc2b38 100644 --- a/why-python.qmd +++ b/why-python.qmd @@ -4,57 +4,118 @@ 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" date: "2023-03-22" -date-modified: last-modified 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 +::: content-hidden +State the context and some background on the issue, then write a +statement in the form of a question for the problem. +::: + +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 Seedcase 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. +> Which programming language should we use for developing the Seedcase application? + +## 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 context of Seedcase 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. + ## Considered Options -We considered [Python](https://www.python.org), [Java](https://www.java.com/en/), [C++](https://cplusplus.com), and [R](https://www.r-project.org). +::: content-hidden +List and describe some of the options, as well as some of the benefits and +drawbacks for each option. +::: + +### C++ + +::: {.columns} +::: {.column} +#### Benefits + +- Item 1 +::: +::: {.column} +#### Drawbacks + +- Item 1 +::: +::: + +### Java + +::: {.columns} +::: {.column} +#### Benefits + +- Item 1 +::: +::: {.column} +#### Drawbacks + +- Item 1 +::: +::: + +### Python + +::: {.columns} +::: {.column} +#### Benefits + +- Item 1 +::: +::: {.column} +#### Drawbacks + +- Item 1 +::: +::: + +### R + +::: {.columns} +::: {.column} +#### Benefits + +- Item 1 +::: +::: {.column} +#### Drawbacks + +- Item 1 +::: +::: ## Decision Outcome -We have decided to use Python as the main development language for the -following reasons: - -- 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. - -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. - -## Conclusion - -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. +::: content-hidden +What decision was made, use the form "We decided on CHOICE because of +REASONS." +::: + + + +### Consequences + +::: content-hidden +List some potential consequences of this decision. +::: diff --git a/why-ruff.qmd b/why-ruff.qmd index 217beeb..f4d036b 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 @@ -24,7 +21,7 @@ categories: ## 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? @@ -38,7 +35,7 @@ Humans are prone to error when writing, whether it is code or text. In a team se 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,9 +119,14 @@ 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 @@ -105,5 +134,5 @@ We decided on Ruff because it is a newer tool that implements many of the other ## 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-standard-shortcuts.qmd b/why-standard-shortcuts.qmd index 2bd3f39..307244f 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 @@ -29,8 +28,6 @@ As the documentation for Seedcase growing, and we have reached a level where it 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 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. diff --git a/why-text-based.qmd b/why-text-based.qmd index 046fb32..fee69ea 100644 --- a/why-text-based.qmd +++ b/why-text-based.qmd @@ -1,16 +1,14 @@ --- 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 - code - text --- - -TODO: Need to fill this in, later. + "Everything as code" From 52f117957891834867874da17d8b83df1d3a0278 Mon Sep 17 00:00:00 2001 From: martonvago Date: Fri, 10 May 2024 13:23:21 +0200 Subject: [PATCH 03/60] docs: :memo: include comparison of languages in Why Python post --- why-python.qmd | 64 ++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 49 insertions(+), 15 deletions(-) diff --git a/why-python.qmd b/why-python.qmd index 9bc2b38..46b1e43 100644 --- a/why-python.qmd +++ b/why-python.qmd @@ -2,9 +2,8 @@ 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. -date: "2023-03-22" + As it is used across multiple domains and industries, it is likely to be familiar to a wider audience. +date: "2024-05-10" categories: - programming - development @@ -23,9 +22,7 @@ State the context and some background on the issue, then write a statement in the form of a question for the problem. ::: -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 Seedcase 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. +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 Seedcase 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 a research context. > Which programming language should we use for developing the Seedcase application? @@ -36,7 +33,7 @@ List some reasons for why we need to make this decision and what things have arisen that impact work. ::: -In the context of Seedcase 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. +In the context of Seedcase 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 a research context. There is also a consideration with regard to the skills already available in the core team, as we would like to minimise the amount of time needed to program the application. ## Considered Options @@ -51,12 +48,24 @@ drawbacks for each option. ::: {.column} #### Benefits -- Item 1 +- 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 and 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 -- Item 1 +- 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. ::: ::: @@ -66,12 +75,20 @@ drawbacks for each option. ::: {.column} #### Benefits -- Item 1 +- 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 -- Item 1 +- 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. ::: ::: @@ -81,12 +98,18 @@ drawbacks for each option. ::: {.column} #### Benefits -- Item 1 +- 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 ORM), 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 -- Item 1 +- 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. ::: ::: @@ -96,12 +119,16 @@ drawbacks for each option. ::: {.column} #### Benefits -- Item 1 +- Designed for statistical computing with excellent data visualisation capabilities. +- Wide array of libraries 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 -- Item 1 +- 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. ::: ::: @@ -112,6 +139,11 @@ 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 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, 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 @@ -119,3 +151,5 @@ REASONS." ::: 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. \ No newline at end of file From 6c8239ce050edfc8316eea2a4c1f394e9b33d453 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= <40836345+signekb@users.noreply.github.com> Date: Mon, 13 May 2024 09:51:55 +0200 Subject: [PATCH 04/60] fix: change headers to sentence case Quoting @lwjohnst86 : General style guidelines (for documents) tend to suggest sentence case for headers, unless following very specific style guides like MLA/Chicago. E.g. https://developers.google.com/style/capitalization and https://learn.microsoft.com/en-us/powershell/scripting/community/contributing/general-markdown?view=powershell-7.4 and https://www.grammarly.com/blog/title-case-sentence-case/ and https://www.gov.uk/guidance/style-guide/a-to-z-of-gov-uk-style --- _template.qmd | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/_template.qmd b/_template.qmd index 899e475..7cb4c43 100644 --- a/_template.qmd +++ b/_template.qmd @@ -10,21 +10,21 @@ categories: 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 @@ -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 From c39ba00a85eba2d1fe682baca6ace2e38d85f0cd Mon Sep 17 00:00:00 2001 From: Kris Beicher <112945740+K-Beicher@users.noreply.github.com> Date: Wed, 8 May 2024 14:55:59 +0200 Subject: [PATCH 05/60] docs: format sub-set of files to comply with template-1 --- _template.qmd | 4 ++-- why-containers.qmd | 2 -- why-cyclical-workflow.qmd | 5 +++-- why-docker.qmd | 2 -- why-fly.qmd | 1 - why-github-flow.qmd | 7 +++---- 6 files changed, 8 insertions(+), 13 deletions(-) diff --git a/_template.qmd b/_template.qmd index 7cb4c43..a7b255d 100644 --- a/_template.qmd +++ b/_template.qmd @@ -1,13 +1,13 @@ --- 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 diff --git a/why-containers.qmd b/why-containers.qmd index 38d9085..2aa52a0 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 diff --git a/why-cyclical-workflow.qmd b/why-cyclical-workflow.qmd index 078ee67..7c11c4a 100644 --- a/why-cyclical-workflow.qmd +++ b/why-cyclical-workflow.qmd @@ -1,11 +1,12 @@ --- title: "" description: "" -author: "Luke W. Johnston" -date: last-modified +date: "" draft: true # categories: # - --- Follow the tidyverse team approach to repo development, by dedicating periods of time to specific repos, and rotating between. + + \ No newline at end of file diff --git a/why-docker.qmd b/why-docker.qmd index 6420c89..99c0b17 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 diff --git a/why-fly.qmd b/why-fly.qmd index 1b0b6a0..f5646b7 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: diff --git a/why-github-flow.qmd b/why-github-flow.qmd index c2fc848..40a8e88 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 +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 projects. author: family: GitHub issued: @@ -220,4 +219,4 @@ 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. +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. From 673873dfa73ed53746961562083fe64be8d0c0bd Mon Sep 17 00:00:00 2001 From: Kris Beicher <112945740+K-Beicher@users.noreply.github.com> Date: Mon, 13 May 2024 10:56:10 +0200 Subject: [PATCH 06/60] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Minor updates from SKB Co-authored-by: Signe Kirk Brødbæk <40836345+signekb@users.noreply.github.com> --- why-cyclical-workflow.qmd | 2 +- why-github-flow.qmd | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/why-cyclical-workflow.qmd b/why-cyclical-workflow.qmd index 7c11c4a..c5f6e05 100644 --- a/why-cyclical-workflow.qmd +++ b/why-cyclical-workflow.qmd @@ -1,5 +1,5 @@ --- -title: "" +title: "Why cyclical workflow" description: "" date: "" draft: true diff --git a/why-github-flow.qmd b/why-github-flow.qmd index 40a8e88..1405067 100644 --- a/why-github-flow.qmd +++ b/why-github-flow.qmd @@ -1,5 +1,5 @@ --- -title: "Why GitHub Flow" +title: "Why GitHub flow" description: "Our reasons for using the GitHub Flow as our branching and development strategy." date: "2024-02-15" categories: @@ -63,7 +63,7 @@ references: year: n.d. URL: https://githubflow.github.io - id: githubflow - title: GitHub flow - Follow GitHub flow to collaborate projects. + title: GitHub flow - Follow GitHub flow to collaborate on projects. author: family: GitHub issued: From 0b9d2096c8a508c7e23d6181170fd8d45c4721ef Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Mon, 13 May 2024 12:13:15 +0200 Subject: [PATCH 07/60] docs: apply suggestions from review --- why-github-flow.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/why-github-flow.qmd b/why-github-flow.qmd index 1405067..1892c3a 100644 --- a/why-github-flow.qmd +++ b/why-github-flow.qmd @@ -1,6 +1,6 @@ --- title: "Why GitHub flow" -description: "Our reasons for using the GitHub Flow as our branching and development strategy." +description: "Our reasons for using the GitHub flow as our branching and development strategy." date: "2024-02-15" categories: - decision From b059afd806cdf9ccc57e47f03680944d345781f9 Mon Sep 17 00:00:00 2001 From: Kris Beicher <112945740+K-Beicher@users.noreply.github.com> Date: Wed, 8 May 2024 15:02:18 +0200 Subject: [PATCH 08/60] docs: format sub-set of files to comply with template-3 this is the branch containing the python file changes --- why-postgres.qmd | 17 +++-- why-python.qmd | 135 +++++++++++++++++++++++++++---------- why-ruff.qmd | 75 ++++++++++++++------- why-standard-shortcuts.qmd | 5 +- why-text-based.qmd | 6 +- 5 files changed, 161 insertions(+), 77 deletions(-) diff --git a/why-postgres.qmd b/why-postgres.qmd index 54af787..8a8aa0a 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 @@ -37,7 +36,7 @@ One of the most important functions of Seedcase is to handle data, and the most [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 @@ -50,7 +49,7 @@ One of the most important functions of Seedcase is to handle data, and the most * There are a number of ways for MySQL to interact with Apache Parquet files. ::: -::: {.column style="font-size: 90%"} +::: {.column} #### Drawbacks @@ -66,7 +65,7 @@ One of the most important functions of Seedcase is to handle data, and the most [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%"} +::: {.column} #### Benefits @@ -81,7 +80,7 @@ One of the most important functions of Seedcase is to handle data, and the most * It is possible to create columnar based tables directly in PostgreSQL. ::: -::: {.column style="font-size: 90%"} +::: {.column} #### Drawbacks @@ -95,7 +94,7 @@ One of the most important functions of Seedcase is to handle data, and the most 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%"} +::: {.column} #### Benefits @@ -106,7 +105,7 @@ First released in 2000, SQLite is slightly different to the two systems describe * 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 @@ -121,7 +120,7 @@ First released in 2000, SQLite is slightly different to the two systems describe ## 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 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. ### Consequences diff --git a/why-python.qmd b/why-python.qmd index c6a4cb8..9bc2b38 100644 --- a/why-python.qmd +++ b/why-python.qmd @@ -4,57 +4,118 @@ 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" date: "2023-03-22" -date-modified: last-modified 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 +::: content-hidden +State the context and some background on the issue, then write a +statement in the form of a question for the problem. +::: + +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 Seedcase 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. +> Which programming language should we use for developing the Seedcase application? + +## 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 context of Seedcase 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. + ## Considered Options -We considered [Python](https://www.python.org), [Java](https://www.java.com/en/), [C++](https://cplusplus.com), and [R](https://www.r-project.org). +::: content-hidden +List and describe some of the options, as well as some of the benefits and +drawbacks for each option. +::: + +### C++ + +::: {.columns} +::: {.column} +#### Benefits + +- Item 1 +::: +::: {.column} +#### Drawbacks + +- Item 1 +::: +::: + +### Java + +::: {.columns} +::: {.column} +#### Benefits + +- Item 1 +::: +::: {.column} +#### Drawbacks + +- Item 1 +::: +::: + +### Python + +::: {.columns} +::: {.column} +#### Benefits + +- Item 1 +::: +::: {.column} +#### Drawbacks + +- Item 1 +::: +::: + +### R + +::: {.columns} +::: {.column} +#### Benefits + +- Item 1 +::: +::: {.column} +#### Drawbacks + +- Item 1 +::: +::: ## Decision Outcome -We have decided to use Python as the main development language for the -following reasons: - -- 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. - -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. - -## Conclusion - -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. +::: content-hidden +What decision was made, use the form "We decided on CHOICE because of +REASONS." +::: + + + +### Consequences + +::: content-hidden +List some potential consequences of this decision. +::: diff --git a/why-ruff.qmd b/why-ruff.qmd index 217beeb..f4d036b 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 @@ -24,7 +21,7 @@ categories: ## 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? @@ -38,7 +35,7 @@ Humans are prone to error when writing, whether it is code or text. In a team se 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,9 +119,14 @@ 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 @@ -105,5 +134,5 @@ We decided on Ruff because it is a newer tool that implements many of the other ## 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-standard-shortcuts.qmd b/why-standard-shortcuts.qmd index 2bd3f39..307244f 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 @@ -29,8 +28,6 @@ As the documentation for Seedcase growing, and we have reached a level where it 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 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. diff --git a/why-text-based.qmd b/why-text-based.qmd index 046fb32..fee69ea 100644 --- a/why-text-based.qmd +++ b/why-text-based.qmd @@ -1,16 +1,14 @@ --- 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 - code - text --- - -TODO: Need to fill this in, later. + "Everything as code" From fce7d7cfdbfc2764bea273d1c3556ce48ebe0a7d Mon Sep 17 00:00:00 2001 From: Kris Beicher <112945740+K-Beicher@users.noreply.github.com> Date: Fri, 10 May 2024 14:56:27 +0200 Subject: [PATCH 09/60] docs: update why text based with template --- why-text-based.qmd | 53 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 53 insertions(+) diff --git a/why-text-based.qmd b/why-text-based.qmd index fee69ea..fb3a69b 100644 --- a/why-text-based.qmd +++ b/why-text-based.qmd @@ -25,3 +25,56 @@ https://octopus.com/blog/what-is-everything-as-code 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 + +::: 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 + +::: 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. +::: + +### Option 1 + +::: {.columns} +::: {.column} +#### Benefits + +- Item 1 +::: +::: {.column} +#### Drawbacks + +- Item 1 +::: +::: + +## Decision Outcome + +::: content-hidden +What decision was made, use the form "We decided on CHOICE because of +REASONS." +::: + +### Consequences + +::: content-hidden +List some potential consequences of this decision. +::: From 8ff0507489d62939ab46531282534193534dd332 Mon Sep 17 00:00:00 2001 From: Kris Beicher <112945740+K-Beicher@users.noreply.github.com> Date: Wed, 8 May 2024 14:59:07 +0200 Subject: [PATCH 10/60] docs: format sub-set of files to comply with template-2 --- why-github-projects.qmd | 5 +- why-github.qmd | 28 ++++-- why-material-design.qmd | 79 +++++++++++----- why-mit-license.qmd | 2 +- why-poetry.qmd | 203 +++++++++++++++++++++++++++------------- why-polyrepo.qmd | 5 +- 6 files changed, 220 insertions(+), 102 deletions(-) diff --git a/why-github-projects.qmd b/why-github-projects.qmd index 6a74aeb..894874b 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,6 +14,8 @@ categories: - workflow --- + + ## 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: diff --git a/why-github.qmd b/why-github.qmd index 1d5cc46..06622a5 100644 --- a/why-github.qmd +++ b/why-github.qmd @@ -1,14 +1,13 @@ --- title: "" description: "Our reasons for ..." -author: "" -date: last-modified -draft: true -# categories: +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 @@ -28,8 +27,23 @@ have arisen that impact work. ## 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 diff --git a/why-material-design.qmd b/why-material-design.qmd index 4b3f1b5..9874527 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 +date: "2023-12-15" categories: - user interface - user experience @@ -31,45 +30,73 @@ We have considered the following: [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. -- **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. +::: {.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/) (used for sketching out the UI) has great support for Material Design +::: +::: {.column} +#### Drawbacks + +- 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. -- **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 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. diff --git a/why-mit-license.qmd b/why-mit-license.qmd index 569b3e9..3d7e728 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: @@ -10,6 +9,7 @@ categories: - copyright - software-architecture --- + ## Context and Problem Statement diff --git a/why-poetry.qmd b/why-poetry.qmd index 913b3cd..8e002e0 100644 --- a/why-poetry.qmd +++ b/why-poetry.qmd @@ -1,8 +1,7 @@ --- 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 @@ -11,95 +10,173 @@ categories: ## 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. +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. +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. +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. +- 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. +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: -- [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/) +- [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/) ### 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. +[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. -- **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) +::: columns +::: column +#### Benefits + +- Is very popular and widely used +- Has been around for a while +- Only handles package dependencies (no other features) + +::: + +::: column +#### Drawbacks + +- 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 -[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 +[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. + +::: 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 + + +- 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 -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 \ No newline at end of file diff --git a/why-polyrepo.qmd b/why-polyrepo.qmd index 3b501a5..f54dbdc 100644 --- a/why-polyrepo.qmd +++ b/why-polyrepo.qmd @@ -1,15 +1,14 @@ --- 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 - structure - management --- - + ## Context and Problem Statement The core issue and question here is: From 846352e04f3862cf1ddc23407ecddd5eebc1f8fa Mon Sep 17 00:00:00 2001 From: Kris Beicher <112945740+K-Beicher@users.noreply.github.com> Date: Fri, 10 May 2024 14:53:17 +0200 Subject: [PATCH 11/60] docs: update github projects with coding for benefits-drawbacks --- why-github-projects.qmd | 36 +++++++++++++++++++++++++++--------- 1 file changed, 27 insertions(+), 9 deletions(-) diff --git a/why-github-projects.qmd b/why-github-projects.qmd index 894874b..5e05464 100644 --- a/why-github-projects.qmd +++ b/why-github-projects.qmd @@ -32,21 +32,39 @@ As a team we have been struggling to keep track of who is completing which tasks 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 From 5c6c8aa967c4c1234277f80c818bb252996c4e54 Mon Sep 17 00:00:00 2001 From: Kris Beicher <112945740+K-Beicher@users.noreply.github.com> Date: Mon, 13 May 2024 10:58:09 +0200 Subject: [PATCH 12/60] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Minor changes from SKB Co-authored-by: Signe Kirk Brødbæk <40836345+signekb@users.noreply.github.com> --- why-material-design.qmd | 6 +++++- why-poetry.qmd | 2 -- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/why-material-design.qmd b/why-material-design.qmd index 9874527..d8b86b7 100644 --- a/why-material-design.qmd +++ b/why-material-design.qmd @@ -57,7 +57,7 @@ We have considered the following: - 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 +- [Figma](https://www.figma.com/) (which can be used for sketching out the UI) has great support for Material Design ::: ::: {.column} #### Drawbacks @@ -73,11 +73,13 @@ We have considered the following: ::: {.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 ::: @@ -90,10 +92,12 @@ We have considered the following: ::: {.columns} ::: {.column} #### Benefits + - Seems relatively easy to use ::: ::: {.column} #### Drawbacks + - Requires Node.js (via npm) to install ::: ::: diff --git a/why-poetry.qmd b/why-poetry.qmd index 8e002e0..ed6c04e 100644 --- a/why-poetry.qmd +++ b/why-poetry.qmd @@ -93,7 +93,6 @@ package management and project development in mind. ::: 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) @@ -109,7 +108,6 @@ package management and project development in mind. ::: column #### Drawbacks - - 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 From a9412c0996b1a60bd1dbd4892481387d8b9f0cac Mon Sep 17 00:00:00 2001 From: Kris Beicher <112945740+K-Beicher@users.noreply.github.com> Date: Wed, 8 May 2024 14:35:36 +0200 Subject: [PATCH 13/60] docs: complete update to why discord --- why-discord.qmd | 170 +++++++++++++++++++++++++++++++++--------------- 1 file changed, 118 insertions(+), 52 deletions(-) diff --git a/why-discord.qmd b/why-discord.qmd index fdeece3..0388dce 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 IMs 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 From b20083c284a10a311c56709ad0266db4d7d42ca7 Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Mon, 13 May 2024 12:19:34 +0200 Subject: [PATCH 14/60] docs: apply suggestions from review --- why-discord.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/why-discord.qmd b/why-discord.qmd index 0388dce..7f4fb27 100644 --- a/why-discord.qmd +++ b/why-discord.qmd @@ -18,7 +18,7 @@ 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 IMs like Slack. While email is a great tool +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 From 988732bb0087f21ce43e2064dbb249da6b8aa413 Mon Sep 17 00:00:00 2001 From: lwjohnst86 Date: Tue, 7 May 2024 12:45:35 +0000 Subject: [PATCH 15/60] =?UTF-8?q?=F0=9F=94=84=20synced=20local=20'.gitigno?= =?UTF-8?q?re'=20with=20remote=20'.gitignore'?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .gitignore | 6 ++++++ 1 file changed, 6 insertions(+) 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 From b0907cf55679e65aa8983fcea5e0c465d68778b1 Mon Sep 17 00:00:00 2001 From: lwjohnst86 Date: Tue, 7 May 2024 12:45:35 +0000 Subject: [PATCH 16/60] =?UTF-8?q?=F0=9F=94=84=20synced=20local=20'.vscode/?= =?UTF-8?q?settings.json'=20with=20remote=20'.vscode/settings.json'?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .vscode/settings.json | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index 5450c82..2d42ace 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,11 @@ "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 +} From 0e70708c5b46ebf15572d58e8047c6c85b0b1c82 Mon Sep 17 00:00:00 2001 From: lwjohnst86 Date: Tue, 7 May 2024 12:45:35 +0000 Subject: [PATCH 17/60] =?UTF-8?q?=F0=9F=94=84=20synced=20local=20'.vscode/?= =?UTF-8?q?extensions.json'=20with=20remote=20'.vscode/extensions.json'?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .vscode/extensions.json | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) 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 From 5c3845b49791b64f995043d791c717709d2f8234 Mon Sep 17 00:00:00 2001 From: martonvago <57952344+martonvago@users.noreply.github.com> Date: Mon, 13 May 2024 13:51:51 +0200 Subject: [PATCH 18/60] docs: apply suggestions from review Co-authored-by: Luke W. Johnston --- why-python.qmd | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/why-python.qmd b/why-python.qmd index 721da76..42305e6 100644 --- a/why-python.qmd +++ b/why-python.qmd @@ -3,7 +3,8 @@ title: "Why Python" description: | Python is one of the most common and widely used programming languages. As it is used across multiple domains and industries, it is likely to be familiar to a wider audience. -date: "2024-05-10" +date: "2023-03-22" +date-modified: "2024-05-10" categories: - programming - development @@ -52,7 +53,7 @@ drawbacks for each option. - 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 and by a smaller margin, Java. +- 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. @@ -103,7 +104,7 @@ drawbacks for each option. - 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 ORM), and data analysis. +- 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. ::: @@ -122,7 +123,7 @@ drawbacks for each option. #### Benefits - Designed for statistical computing with excellent data visualisation capabilities. -- Wide array of libraries for data analysis. +- 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. ::: From d04406ff02506e70641c60def07e3c360bf1abaa Mon Sep 17 00:00:00 2001 From: Kris Beicher <112945740+K-Beicher@users.noreply.github.com> Date: Wed, 8 May 2024 14:43:21 +0200 Subject: [PATCH 19/60] docs: complete update to why django --- why-django.qmd | 157 ++++++++++++++++++++++++++++--------------------- 1 file changed, 89 insertions(+), 68 deletions(-) diff --git a/why-django.qmd b/why-django.qmd index a905c15..fd942da 100644 --- a/why-django.qmd +++ b/why-django.qmd @@ -3,9 +3,7 @@ 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" date: "2023-03-22" -date-modified: last-modified categories: - api - web @@ -13,30 +11,79 @@ categories: - software-architecture --- - + -## Introduction +::: content-hidden +Use other decision posts as inspiration to writing these. Leave the +content-hidden sections in the text for future reference. +::: -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. +## Context and Problem Statement -## Decision +::: content-hidden +State the context and some background on the issue, then write a +statement in the form of a question for the problem. +::: -After evaluating Flask, Ruby on Rails, FastAPI, and Django, we have -decided to use Django as the web framework for Seedcase. +For a software project to succeed it is important to pick the right +programming framework to work in from the start. A framework should +provide consistency, code reuse, and easy of maintenance for a group of +developers. It should provide best practice, and allow for code to be +shared between different parts of the applications. The question +therefore becomes: -All considered web frameworks use Python. For our decision to use Python, see the page [Why Python](why-python.qmd). +> Which coding framework will best suit our needs in developing +> Seedcase? -## Alternatives Considered +## Decision Drivers + +::: content-hidden +List some reasons for why we need to make this decision and what things +have arisen that impact work. +::: + +All considered web frameworks use Python. For our decision to use +Python, see the page [Why Python](why-python.qmd). + +## 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) 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. + +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. + +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. + +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. ### 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. +[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 @@ -45,11 +92,11 @@ 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. +[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 @@ -58,57 +105,31 @@ on Rails has a large footprint and can be slow for certain use cases. ### 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 +[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. +## Decision Outcome -## Conclusion +::: content-hidden +What decision was made, use the form "We decided on CHOICE because of +REASONS." +::: 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 +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 From 0a9de39487db5e94207bdfbbd9d9979bf2cb95b1 Mon Sep 17 00:00:00 2001 From: Kris Beicher <112945740+K-Beicher@users.noreply.github.com> Date: Fri, 10 May 2024 14:48:22 +0200 Subject: [PATCH 20/60] docs: update with options code --- why-django.qmd | 56 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 56 insertions(+) diff --git a/why-django.qmd b/why-django.qmd index fd942da..18563ef 100644 --- a/why-django.qmd +++ b/why-django.qmd @@ -77,6 +77,20 @@ authentication system and its support for user profiles and social authentication. It also provides good support for password resets and account activation. + +::: {.columns} +::: {.column} +#### Benefits + +- Item 1 +::: +::: {.column} +#### Drawbacks + +- Item 1 +::: +::: + ### Flask [Flask](https://flask.palletsprojects.com/en/2.3.x/) is a lightweight @@ -90,6 +104,20 @@ 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. + +::: {.columns} +::: {.column} +#### Benefits + +- Item 1 +::: +::: {.column} +#### Drawbacks + +- Item 1 +::: +::: + ### Ruby on Rails [Ruby on Rails](https://rubyonrails.org) is a popular web framework that @@ -103,6 +131,20 @@ 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. + +::: {.columns} +::: {.column} +#### Benefits + +- Item 1 +::: +::: {.column} +#### Drawbacks + +- Item 1 +::: +::: + ### FastAPI [FastAPI](https://fastapi.tiangolo.com) is a modern, high-performance @@ -121,6 +163,20 @@ 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. + +::: {.columns} +::: {.column} +#### Benefits + +- Item 1 +::: +::: {.column} +#### Drawbacks + +- Item 1 +::: +::: + ## Decision Outcome ::: content-hidden From 08554dc4b6d3db70c388457f833797a980cc1e5b Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Mon, 13 May 2024 14:18:32 +0200 Subject: [PATCH 21/60] docs: :memo: removed the ruby on rails, since it uses Ruby not Python --- why-django.qmd | 29 +---------------------------- 1 file changed, 1 insertion(+), 28 deletions(-) diff --git a/why-django.qmd b/why-django.qmd index 18563ef..d5850b0 100644 --- a/why-django.qmd +++ b/why-django.qmd @@ -105,33 +105,6 @@ Django has, such as an admin interface, an object-relational mapper to be implemented manually or by using third-party libraries. -::: {.columns} -::: {.column} -#### Benefits - -- Item 1 -::: -::: {.column} -#### Drawbacks - -- Item 1 -::: -::: - -### 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. - - ::: {.columns} ::: {.column} #### Benefits @@ -188,4 +161,4 @@ 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 +security, as well as user management. From 9f8697913a8532c4cde9ada70e361b793ba3069d Mon Sep 17 00:00:00 2001 From: Kris Beicher <112945740+K-Beicher@users.noreply.github.com> Date: Wed, 8 May 2024 14:47:00 +0200 Subject: [PATCH 22/60] docs: complete update to why quarto --- why-quarto.qmd | 62 ++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 55 insertions(+), 7 deletions(-) diff --git a/why-quarto.qmd b/why-quarto.qmd index 0218194..b96ceef 100644 --- a/why-quarto.qmd +++ b/why-quarto.qmd @@ -1,15 +1,41 @@ --- 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 with +potential users that are not prime candidates to use Github. The easiest +way to do this is by having 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 manage a website with the smallest amount of overhead when +> we consider that we are already using GitHub? + +## 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 @@ -23,11 +49,23 @@ writing the documentation for Seedcase itself. meaning it is a simple file that is being shown by the browser as a webpage. +## Considered Options + +::: content-hidden +List and describe some of the options, as well as some of the benefits +and drawbacks for each option. +::: + + + +### 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. +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. @@ -47,5 +85,15 @@ for multiple reasons. the de facto standard for writing Markdown, with strong historical use and community support. -For these reasons, we write our documentation that includes the website -with Quarto. +## Decision Outcome + +::: content-hidden +What decision was made, use the form "We decided on CHOICE because of +REASONS." +::: + +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. + + \ No newline at end of file From 95e7a14866738b8f51f60241cd462975a6d6ddff Mon Sep 17 00:00:00 2001 From: Kris Beicher <112945740+K-Beicher@users.noreply.github.com> Date: Fri, 10 May 2024 11:24:24 +0200 Subject: [PATCH 23/60] update to template part --- why-quarto.qmd | 69 ++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 55 insertions(+), 14 deletions(-) diff --git a/why-quarto.qmd b/why-quarto.qmd index b96ceef..582c036 100644 --- a/why-quarto.qmd +++ b/why-quarto.qmd @@ -67,23 +67,64 @@ 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 +::: {.columns} +::: {.column} +#### Benefits + +- It is open source +- The documentation is phenomenal and very beginner friendly +- 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, - which makes it easier to use compared to other alternatives. -5. 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 + projects +- The software design is extremely well developed and structured, + which makes it easier to use compared to other alternatives +- It has multi-language support (like R and Python), but is itself + language-agnostic +- Because it is integrated into RStudio, many data scientists and + researchers who use R will quickly become familiar with it +- 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 + software developers and data scientists +- 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. + use and community support +::: +::: {.column} +#### Drawbacks + +- TBC +::: +::: + +### Jekyll + +::: {.columns} +::: {.column} +#### Benefits + +- TBC +::: +::: {.column} +#### Drawbacks + +- TBC +::: +::: + +### Hugo + +::: {.columns} +::: {.column} +#### Benefits + +- TBC +::: +::: {.column} +#### Drawbacks + +- TBC +::: +::: ## Decision Outcome From b5aa2eca1972f8bfea77abd8aaa6551f962a2f47 Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Tue, 14 May 2024 18:48:42 +0200 Subject: [PATCH 24/60] docs: :memo: add options for other website generators --- why-quarto.qmd | 170 +++++++++++++++++++++++++++++++++---------------- 1 file changed, 116 insertions(+), 54 deletions(-) diff --git a/why-quarto.qmd b/why-quarto.qmd index 582c036..f50404e 100644 --- a/why-quarto.qmd +++ b/why-quarto.qmd @@ -7,6 +7,7 @@ categories: - markdown - website --- + ::: content-hidden @@ -14,7 +15,7 @@ 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 @@ -22,15 +23,15 @@ statement in the form of a question for the problem. ::: A software project like Seedcase needs an easy way to communicate with -potential users that are not prime candidates to use Github. The easiest -way to do this is by having 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: +potential users that might not be familiar with using Github. The +easiest way to do this is by having 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 manage a website with the smallest amount of overhead when -> we consider that we are already using GitHub? +> 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 +## Decision drivers ::: content-hidden List some reasons for why we need to make this decision and what things @@ -41,7 +42,8 @@ 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 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 @@ -49,6 +51,14 @@ 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. + ## Considered Options ::: content-hidden @@ -56,77 +66,128 @@ 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: -### Quarto +- [mdBook](https://rust-lang.github.io/mdBook/index.html) +- [MkDocs](https://www.mkdocs.org/) +- [Quarto](https://quarto.org/) -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. +### 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} +::: columns +::: column #### Benefits -- It is open source -- The documentation is phenomenal and very beginner friendly -- It is sponsored by an organization ([Posit](https://posit.co/)) with - an established history of supporting and contributing to open source - projects -- The software design is extremely well developed and structured, - which makes it easier to use compared to other alternatives -- It has multi-language support (like R and Python), but is itself - language-agnostic -- Because it is integrated into RStudio, many data scientists and - researchers who use R will quickly become familiar with it -- 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 -- 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 +- Can build websites very quickly because it is built with Rust. +- Simple and clean website design. ::: -::: {.column} + +::: column #### Drawbacks -- TBC +- 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 to know to use the tool. +- Adding extensions and customizing the website requires some + knowledge and learning to use, nor are there 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. ::: ::: -### Jekyll +### 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} +::: columns +::: column #### Benefits -- TBC +- 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} + +::: column #### Drawbacks -- TBC +- 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. ::: ::: -### Hugo +### 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. -::: {.columns} -::: {.column} +::: columns +::: column #### Benefits -- TBC +- 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. +- The software design is extremely well developed and structured, + which makes it easier to use compared to other alternatives. +- It has multi-language support (like R and Python), but is itself + language-agnostic. +- 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. +- 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} + +::: column #### Drawbacks -- TBC +- 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, to effectively develop + features in an extension requires some knowledge of + [Lua](https://www.lua.org). ::: ::: -## Decision Outcome +## Decision outcome ::: content-hidden What decision was made, use the form "We decided on CHOICE because of @@ -135,6 +196,7 @@ REASONS." 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. - - \ No newline at end of file +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. From 36c18d70a3f739c2bb54e45313635720e6cdd097 Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Wed, 15 May 2024 13:58:00 +0200 Subject: [PATCH 25/60] docs: apply suggestions from review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Signe Kirk Brødbæk <40836345+signekb@users.noreply.github.com> --- why-quarto.qmd | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/why-quarto.qmd b/why-quarto.qmd index f50404e..298598e 100644 --- a/why-quarto.qmd +++ b/why-quarto.qmd @@ -8,7 +8,6 @@ categories: - website --- - ::: content-hidden Use other decision posts as inspiration to writing these. Leave the @@ -100,9 +99,9 @@ documentation and includes some basic website features. 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 to know to use the tool. + commands required for using the tool. - Adding extensions and customizing the website requires some - knowledge and learning to use, nor are there many default or + 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 @@ -114,7 +113,7 @@ documentation and includes some basic website features. ::: ::: -### mkDocs +### 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 From cc759efaf8c14703a5f070380e615a96704392c6 Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Wed, 15 May 2024 14:05:36 +0200 Subject: [PATCH 26/60] docs: :memo: updates to quarto decision post based on comments from @signekb --- why-quarto.qmd | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/why-quarto.qmd b/why-quarto.qmd index 298598e..a9f3d79 100644 --- a/why-quarto.qmd +++ b/why-quarto.qmd @@ -8,7 +8,6 @@ categories: - website --- - ::: content-hidden Use other decision posts as inspiration to writing these. Leave the content-hidden sections in the text for future reference. @@ -21,11 +20,12 @@ 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 with -potential users that might not be familiar with using Github. The -easiest way to do this is by having 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: +A software project like Seedcase needs an easy way to communicate and +share knowledge for those internal and external to Seedcase (including +users), 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? @@ -56,7 +56,8 @@ needs when it comes to this decision: 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. +- Uses Markdown as the basis for writing content (see [Why + Markdown](why-markdown.qmd) for reasons on why). ## Considered Options @@ -147,8 +148,10 @@ and fast website generator. ### 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. +[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 @@ -180,8 +183,8 @@ taken over as the tool to use when working with R and data science. - 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, to effectively develop - features in an extension requires some knowledge of +- While not necessary for most purposes, developing certain features + when making a Quarto extension requires some knowledge of [Lua](https://www.lua.org). ::: ::: From 49fcd645370df998175304ef03bfa20192da4bd4 Mon Sep 17 00:00:00 2001 From: "Luke W. Johnston" Date: Wed, 15 May 2024 16:59:54 +0200 Subject: [PATCH 27/60] docs: apply suggestions from review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Signe Kirk Brødbæk <40836345+signekb@users.noreply.github.com> --- why-quarto.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/why-quarto.qmd b/why-quarto.qmd index a9f3d79..d1ab572 100644 --- a/why-quarto.qmd +++ b/why-quarto.qmd @@ -22,7 +22,7 @@ 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), the most common way being to put these content (like +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: From 3c5fc42d6dadd2fbaad25fbc407f1424640c0bc8 Mon Sep 17 00:00:00 2001 From: lwjohnst86 Date: Fri, 17 May 2024 11:56:24 +0000 Subject: [PATCH 28/60] =?UTF-8?q?=F0=9F=94=84=20synced=20local=20'.vscode/?= =?UTF-8?q?settings.json'=20with=20remote=20'.vscode/settings.json'?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .vscode/settings.json | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.vscode/settings.json b/.vscode/settings.json index 2d42ace..b5f7833 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -32,5 +32,9 @@ }, "python.defaultInterpreterPath": "${workspaceFolder}/.venv", "python.languageServer": "Pylance", - "files.insertFinalNewline": true + "files.insertFinalNewline": true, + "cSpell.enableFiletypes": [ + "quarto" + ], + "cSpell.language": "en,en-GB", } From 5a7fece61cc78a4d29aa093f3488a7d31e02da97 Mon Sep 17 00:00:00 2001 From: lwjohnst86 Date: Fri, 17 May 2024 14:48:27 +0000 Subject: [PATCH 29/60] =?UTF-8?q?=F0=9F=94=84=20synced=20local=20'.vscode/?= =?UTF-8?q?json.code-snippets'=20with=20remote=20'.vscode/json.code-snippe?= =?UTF-8?q?ts'?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .vscode/json.code-snippets | 94 ++++++++++++++++++-------------------- 1 file changed, 44 insertions(+), 50 deletions(-) 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 +} From b18e180a2e474833fc3ef744ea49ca54bfb9efd8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Signe=20Kirk=20Br=C3=B8db=C3=A6k?= Date: Wed, 15 May 2024 11:57:16 +0200 Subject: [PATCH 30/60] docs: :memo: init why conventional commits decision post --- why-conventional-commits.qmd | 278 +++++++++++++++++++++++++++++++++++ 1 file changed, 278 insertions(+) create mode 100644 why-conventional-commits.qmd diff --git a/why-conventional-commits.qmd b/why-conventional-commits.qmd new file mode 100644 index 0000000..2956420 --- /dev/null +++ b/why-conventional-commits.qmd @@ -0,0 +1,278 @@ +--- +title: "Why conventional commits (with optional emojis)" +description: "Our reasons for using conventional commits (with optional emojis following the Gitmoji convention) across the Seedcase projects." +date: "2024-05-14" +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 + +::: 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 ease the understanding of the +project history, tracking of changes, and 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 also arise from a clear, +consistent workflow on commit frequency and content (see the decision +post on why we use [atomic commits](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 projects? + +## 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 projects, we emphasise the open-science philosophies of +transparency and collaboration. Therefore, having a clear and consistent +commit message convention is essential for maintaining these principles, +both within the team and for external contributors. + +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 help with the review +process, as the context and purpose of the changes will be clearer for +reviewers. + +In addition, some commit message conventions can automate changelogs and +release processes, which can be beneficial for managing versioning and +communicating changes to users and contributors. + +::: callout-caution +Note that most conventions follow the same general principles with some +differences in syntax and structure. + +In general, a commit message should be **concise** (brief, but +descriptive), **relevant** (focus on *why* the change was necessary, not +*how* it was implemented), **clear** (include specific descriptions, and +avoid vagueness and ambiguity), and **consistent** (follow a standard +format). + +Some of the general principles that most conventions follow are that 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 the 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 are multiple conventions for writing commit messages, but we will +consider three of the most popular ones: the Angular convention, +conventional commits, and the Gitmoji convention. + +### The Angular convention + +The [Angular +convention](https://github.com/angular/angular/blob/22b96b9/CONTRIBUTING.md#-commit-message-guidelines) +includes a **header**, a **body**, and a **footer** in each commit +message, like shown below: + +``` +(): + + + +