From b450caf0370ad768975d54c189cad2b7e38dc82c Mon Sep 17 00:00:00 2001 From: WeissSa Date: Tue, 10 Oct 2023 16:35:08 -0400 Subject: [PATCH 1/5] Added first draft of trunk-based development page --- Topics/Development_Process.md | 60 +++++++++++-------- .../Development_Process/Trunk_Development.md | 5 ++ 2 files changed, 40 insertions(+), 25 deletions(-) create mode 100644 Topics/Development_Process/Trunk_Development.md diff --git a/Topics/Development_Process.md b/Topics/Development_Process.md index 7aaf37faf..92b2a54bc 100644 --- a/Topics/Development_Process.md +++ b/Topics/Development_Process.md @@ -1,68 +1,78 @@ ## Resources for Development Process + ## Git + ### [Learning Git](./Development_Process/Git/Git.md) +### [Trunk-Based Development](./Development_Process/Trunk_Development.md) + ### [Django Project Deployment: AWS, Vercel, and Railway](./Development_Process/Django_Deployment_AWS_Railway_Vercel.md) + ### [Automated Frontend Deployment with Vercel](./Development_Process/Frontend_Automated_Deployment_Vercel.md) + ### [Quality Assurance Testing](./Development_Process/QA_testing.md) + - [Automated Testing](./Development_Process/Automated_Testing.md) ### [Getting Started With Docker](./Development_Process/Docker.md) - ## Build requirements + ### [Requirements.txt](./Development_Process/Build_Requirements/Requirements_txt.md) ## React Testing Library + ### [React Testing Library](./Development_Process/React_Testing_Library.md) -## SOLID PRINCIPLES: +## SOLID PRINCIPLES: SOLID is a mnemonic acronym that represents a set of five very important software development principles which lead to code that is easier to read, maintain, and extend, leading to higher-quality software that is easier to evolve over time. The SOLID principles are: - - Single Responsibility Principle (SRP): A class should only have one cause to change, according to the Single Responsibility Principle (SRP). According to this theory, a class ought to have just one duty, which implies that there ought to be just one motivation for change. This makes the class more understandable, maintainable, and reuseable as well as more flexible. +- Single Responsibility Principle (SRP): A class should only have one cause to change, according to the Single Responsibility Principle (SRP). According to this theory, a class ought to have just one duty, which implies that there ought to be just one motivation for change. This makes the class more understandable, maintainable, and reuseable as well as more flexible. + +- Open/Closed Principle (OCP): Software entities (classes, modules, functions, etc.) should be available for extension but closed for modification, according to the available/Closed Principle (OCP). According to this principle, a system should be able to introduce new functionality without requiring changes to the existing code. Interfaces, polymorphism, and generalization are used to accomplish this. + +- Liskov Substitution Principle (LSP): Subtypes must be able to be used in place of their parent types. According to this concept, it should be possible to swap out objects from a superclass for objects from a subclass without having any negative effects on the program's correctness. This necessitates abiding by the superclass's compact. + +- Interface Segregation Principle (ISP): Clients should not be forced to depend on interfaces they do not use. This principle states that a client should not be forced to implement an interface if it does not use all of the methods defined by the interface. This helps to avoid the creation of fat interfaces, which are interfaces that contain more methods than the client needs. - - Open/Closed Principle (OCP): Software entities (classes, modules, functions, etc.) should be available for extension but closed for modification, according to the available/Closed Principle (OCP). According to this principle, a system should be able to introduce new functionality without requiring changes to the existing code. Interfaces, polymorphism, and generalization are used to accomplish this. +- Dependency Inversion Principle (DIP): High-level modules should not depend on low-level modules. Both should depend on abstractions. Abstractions should not depend on details. Details should depend on abstractions. This principle suggests that classes should depend on abstractions rather than concrete implementations, which makes the system more flexible and easier to modify. - - Liskov Substitution Principle (LSP): Subtypes must be able to be used in place of their parent types. According to this concept, it should be possible to swap out objects from a superclass for objects from a subclass without having any negative effects on the program's correctness. This necessitates abiding by the superclass's compact. +## Resource that gives examples of the uses cases of SOLID principles - - Interface Segregation Principle (ISP): Clients should not be forced to depend on interfaces they do not use. This principle states that a client should not be forced to implement an interface if it does not use all of the methods defined by the interface. This helps to avoid the creation of fat interfaces, which are interfaces that contain more methods than the client needs. +LINK : https://www.youtube.com/watch?v=_jDNAf3CzeY + +## Clean Architecture: - - Dependency Inversion Principle (DIP): High-level modules should not depend on low-level modules. Both should depend on abstractions. Abstractions should not depend on details. Details should depend on abstractions. This principle suggests that classes should depend on abstractions rather than concrete implementations, which makes the system more flexible and easier to modify. - - - ## Resource that gives examples of the uses cases of SOLID principles - LINK : https://www.youtube.com/watch?v=_jDNAf3CzeY - - ## Clean Architecture: - A system's design that divides it into logical parts and specifies how those parts may communicate with one another is referred to as clean architecture. The objective is to make the software system easier to design, deploy, operate, and maintain while still keeping as many options open  for as long as possible. Clean Architecture works on the well-defined division of layers. It is important to understand what the different layers are and which layers are allowed to interact with each other. The independence that clean architecute introduced to the a software system is vital since it reduces dependancies within the system. In clean architecture, the elements of the inner most layers should not have any information about the outermost layers. Anything declared in an outer layer must not be used anywhere within the inner layer of the code. -![image](https://user-images.githubusercontent.com/75923742/227027780-b5fbf347-ff78-49fa-a122-8f9ac4ef53d4.png) +![image](https://user-images.githubusercontent.com/75923742/227027780-b5fbf347-ff78-49fa-a122-8f9ac4ef53d4.png) + +Some of the layers are (Simplified): +- Business Rules: -Some of the layers are (Simplified): -- Business Rules: - Entity: A component of our computer system that represents a condensed set of critical business rules that are applied to crucial business data. - Use Case: Gives specifics on the input the user must supply and the output the system must deliver to the user. Additionally, it includes the processing steps required to create the result. -- Entities: Contains functions, variables, and other structures that hold the main objectives of our application, they must be general and have the highest level of rules. -- Interface Adaptors: Responsible for communicating between the layers, takes data in and transforms it such that it can be sent to lower levels. +- Entities: Contains functions, variables, and other structures that hold the main objectives of our application, they must be general and have the highest level of rules. +- Interface Adaptors: Responsible for communicating between the layers, takes data in and transforms it such that it can be sent to lower levels. - Framworks and Drivers: This section contains frameworks and databases responsible for communicating with the interface adapters. +This is only a simplification of what "Clean Architecture" is; the topic is so vast that there have been texts that have been dedicated to this topic. Some resources that can be beneficial in understanding and clearing up any doubts about the topic have been linked below. -This is only a simplification of what "Clean Architecture" is; the topic is so vast that there have been texts that have been dedicated to this topic. Some resources that can be beneficial in understanding and clearing up any doubts about the topic have been linked below. +- Text that goes into greater depth about each layer: -- Text that goes into greater depth about each layer: - - https://dev.to/rubemfsv/clean-architecture-the-concept-behind-the-code-52do#:~:text=The%20main%20rule%20for%20Clean,elements%20of%20an%20outermost%20layer. + - https://dev.to/rubemfsv/clean-architecture-the-concept-behind-the-code-52do#:~:text=The%20main%20rule%20for%20Clean,elements%20of%20an%20outermost%20layer. - Article Summarizing Clean Architecture (Examples and Code) - - https://pusher.com/tutorials/clean-architecture-introduction/ + + - https://pusher.com/tutorials/clean-architecture-introduction/ - A very detailed explanation of Clean Architecture by Robert C. Martin or Uncle Bob and his book - - https://www.youtube.com/watch?v=2dKZ-dWaCiU - - https://github.com/ropalma/ICMC-USP/blob/master/Book%20-%20Clean%20Architecture%20-%20Robert%20Cecil%20Martin.pdf + - https://www.youtube.com/watch?v=2dKZ-dWaCiU + - https://github.com/ropalma/ICMC-USP/blob/master/Book%20-%20Clean%20Architecture%20-%20Robert%20Cecil%20Martin.pdf diff --git a/Topics/Development_Process/Trunk_Development.md b/Topics/Development_Process/Trunk_Development.md new file mode 100644 index 000000000..fa4801311 --- /dev/null +++ b/Topics/Development_Process/Trunk_Development.md @@ -0,0 +1,5 @@ +### Trunk-Based Development + +Knowing how to manage the creation of large new features in your repository is an important skill, especially working in large organizations or on projects with a complete CI systems. It can be tempting to have large feature branches with hundreds of new lines of code and it can seem daunting to implement a large feature in small stages. Trunk-based development is a system to handle large changes like this. It focuses on creating small PR and using tools such as feature flags. The following article from Atlassian does a great job discussing all the benefits of trunk-based development (i.e. impact on automated testing, having less active branches, and more): **[Atlassian Article](https://www.atlassian.com/continuous-delivery/continuous-integration/trunk-based-development)** + +Instead of using feature flags, one can also use the "branch by abstraction" method found in [this article](https://trunkbaseddevelopment.com/branch-by-abstraction/). This is similar to referencing an interface instead of a class and much like dependency inversion, can both increase or reduce the complexity of your code. From 1ae108c0cd46e779bd40a2af505de7c0523a6f1a Mon Sep 17 00:00:00 2001 From: WeissSa Date: Tue, 10 Oct 2023 16:37:47 -0400 Subject: [PATCH 2/5] fixed prettier formatting Development_process.md incorrectly --- Topics/Development_Process.md | 60 +++++++++++++++-------------------- 1 file changed, 25 insertions(+), 35 deletions(-) diff --git a/Topics/Development_Process.md b/Topics/Development_Process.md index 92b2a54bc..790808108 100644 --- a/Topics/Development_Process.md +++ b/Topics/Development_Process.md @@ -1,78 +1,68 @@ ## Resources for Development Process - ## Git - ### [Learning Git](./Development_Process/Git/Git.md) - ### [Trunk-Based Development](./Development_Process/Trunk_Development.md) - ### [Django Project Deployment: AWS, Vercel, and Railway](./Development_Process/Django_Deployment_AWS_Railway_Vercel.md) - ### [Automated Frontend Deployment with Vercel](./Development_Process/Frontend_Automated_Deployment_Vercel.md) - ### [Quality Assurance Testing](./Development_Process/QA_testing.md) - - [Automated Testing](./Development_Process/Automated_Testing.md) ### [Getting Started With Docker](./Development_Process/Docker.md) -## Build requirements +## Build requirements ### [Requirements.txt](./Development_Process/Build_Requirements/Requirements_txt.md) ## React Testing Library - ### [React Testing Library](./Development_Process/React_Testing_Library.md) -## SOLID PRINCIPLES: +## SOLID PRINCIPLES: SOLID is a mnemonic acronym that represents a set of five very important software development principles which lead to code that is easier to read, maintain, and extend, leading to higher-quality software that is easier to evolve over time. The SOLID principles are: -- Single Responsibility Principle (SRP): A class should only have one cause to change, according to the Single Responsibility Principle (SRP). According to this theory, a class ought to have just one duty, which implies that there ought to be just one motivation for change. This makes the class more understandable, maintainable, and reuseable as well as more flexible. - -- Open/Closed Principle (OCP): Software entities (classes, modules, functions, etc.) should be available for extension but closed for modification, according to the available/Closed Principle (OCP). According to this principle, a system should be able to introduce new functionality without requiring changes to the existing code. Interfaces, polymorphism, and generalization are used to accomplish this. - -- Liskov Substitution Principle (LSP): Subtypes must be able to be used in place of their parent types. According to this concept, it should be possible to swap out objects from a superclass for objects from a subclass without having any negative effects on the program's correctness. This necessitates abiding by the superclass's compact. + - Single Responsibility Principle (SRP): A class should only have one cause to change, according to the Single Responsibility Principle (SRP). According to this theory, a class ought to have just one duty, which implies that there ought to be just one motivation for change. This makes the class more understandable, maintainable, and reuseable as well as more flexible. -- Interface Segregation Principle (ISP): Clients should not be forced to depend on interfaces they do not use. This principle states that a client should not be forced to implement an interface if it does not use all of the methods defined by the interface. This helps to avoid the creation of fat interfaces, which are interfaces that contain more methods than the client needs. + - Open/Closed Principle (OCP): Software entities (classes, modules, functions, etc.) should be available for extension but closed for modification, according to the available/Closed Principle (OCP). According to this principle, a system should be able to introduce new functionality without requiring changes to the existing code. Interfaces, polymorphism, and generalization are used to accomplish this. -- Dependency Inversion Principle (DIP): High-level modules should not depend on low-level modules. Both should depend on abstractions. Abstractions should not depend on details. Details should depend on abstractions. This principle suggests that classes should depend on abstractions rather than concrete implementations, which makes the system more flexible and easier to modify. + - Liskov Substitution Principle (LSP): Subtypes must be able to be used in place of their parent types. According to this concept, it should be possible to swap out objects from a superclass for objects from a subclass without having any negative effects on the program's correctness. This necessitates abiding by the superclass's compact. -## Resource that gives examples of the uses cases of SOLID principles - -LINK : https://www.youtube.com/watch?v=_jDNAf3CzeY - -## Clean Architecture: + - Interface Segregation Principle (ISP): Clients should not be forced to depend on interfaces they do not use. This principle states that a client should not be forced to implement an interface if it does not use all of the methods defined by the interface. This helps to avoid the creation of fat interfaces, which are interfaces that contain more methods than the client needs. + - Dependency Inversion Principle (DIP): High-level modules should not depend on low-level modules. Both should depend on abstractions. Abstractions should not depend on details. Details should depend on abstractions. This principle suggests that classes should depend on abstractions rather than concrete implementations, which makes the system more flexible and easier to modify. + + + ## Resource that gives examples of the uses cases of SOLID principles + LINK : https://www.youtube.com/watch?v=_jDNAf3CzeY + + ## Clean Architecture: + A system's design that divides it into logical parts and specifies how those parts may communicate with one another is referred to as clean architecture. The objective is to make the software system easier to design, deploy, operate, and maintain while still keeping as many options open  for as long as possible. Clean Architecture works on the well-defined division of layers. It is important to understand what the different layers are and which layers are allowed to interact with each other. The independence that clean architecute introduced to the a software system is vital since it reduces dependancies within the system. In clean architecture, the elements of the inner most layers should not have any information about the outermost layers. Anything declared in an outer layer must not be used anywhere within the inner layer of the code. -![image](https://user-images.githubusercontent.com/75923742/227027780-b5fbf347-ff78-49fa-a122-8f9ac4ef53d4.png) +![image](https://user-images.githubusercontent.com/75923742/227027780-b5fbf347-ff78-49fa-a122-8f9ac4ef53d4.png) -Some of the layers are (Simplified): - -- Business Rules: +Some of the layers are (Simplified): +- Business Rules: - Entity: A component of our computer system that represents a condensed set of critical business rules that are applied to crucial business data. - Use Case: Gives specifics on the input the user must supply and the output the system must deliver to the user. Additionally, it includes the processing steps required to create the result. -- Entities: Contains functions, variables, and other structures that hold the main objectives of our application, they must be general and have the highest level of rules. -- Interface Adaptors: Responsible for communicating between the layers, takes data in and transforms it such that it can be sent to lower levels. +- Entities: Contains functions, variables, and other structures that hold the main objectives of our application, they must be general and have the highest level of rules. +- Interface Adaptors: Responsible for communicating between the layers, takes data in and transforms it such that it can be sent to lower levels. - Framworks and Drivers: This section contains frameworks and databases responsible for communicating with the interface adapters. -This is only a simplification of what "Clean Architecture" is; the topic is so vast that there have been texts that have been dedicated to this topic. Some resources that can be beneficial in understanding and clearing up any doubts about the topic have been linked below. -- Text that goes into greater depth about each layer: +This is only a simplification of what "Clean Architecture" is; the topic is so vast that there have been texts that have been dedicated to this topic. Some resources that can be beneficial in understanding and clearing up any doubts about the topic have been linked below. - - https://dev.to/rubemfsv/clean-architecture-the-concept-behind-the-code-52do#:~:text=The%20main%20rule%20for%20Clean,elements%20of%20an%20outermost%20layer. +- Text that goes into greater depth about each layer: + - https://dev.to/rubemfsv/clean-architecture-the-concept-behind-the-code-52do#:~:text=The%20main%20rule%20for%20Clean,elements%20of%20an%20outermost%20layer. - Article Summarizing Clean Architecture (Examples and Code) - - - https://pusher.com/tutorials/clean-architecture-introduction/ + - https://pusher.com/tutorials/clean-architecture-introduction/ - A very detailed explanation of Clean Architecture by Robert C. Martin or Uncle Bob and his book - - https://www.youtube.com/watch?v=2dKZ-dWaCiU - - https://github.com/ropalma/ICMC-USP/blob/master/Book%20-%20Clean%20Architecture%20-%20Robert%20Cecil%20Martin.pdf + - https://www.youtube.com/watch?v=2dKZ-dWaCiU + - https://github.com/ropalma/ICMC-USP/blob/master/Book%20-%20Clean%20Architecture%20-%20Robert%20Cecil%20Martin.pdf From b074fe13357f777975bd3c244baa55f8057fc0a9 Mon Sep 17 00:00:00 2001 From: WeissSa Date: Tue, 10 Oct 2023 17:02:20 -0400 Subject: [PATCH 3/5] fixed some typos in first paragraph --- Topics/Development_Process/Trunk_Development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Topics/Development_Process/Trunk_Development.md b/Topics/Development_Process/Trunk_Development.md index fa4801311..b17ec7808 100644 --- a/Topics/Development_Process/Trunk_Development.md +++ b/Topics/Development_Process/Trunk_Development.md @@ -1,5 +1,5 @@ ### Trunk-Based Development -Knowing how to manage the creation of large new features in your repository is an important skill, especially working in large organizations or on projects with a complete CI systems. It can be tempting to have large feature branches with hundreds of new lines of code and it can seem daunting to implement a large feature in small stages. Trunk-based development is a system to handle large changes like this. It focuses on creating small PR and using tools such as feature flags. The following article from Atlassian does a great job discussing all the benefits of trunk-based development (i.e. impact on automated testing, having less active branches, and more): **[Atlassian Article](https://www.atlassian.com/continuous-delivery/continuous-integration/trunk-based-development)** +Knowing how to manage the creation of large new features in your repository is an important skill, especially when working in large organizations or on projects with complete CI systems. It can be tempting to have large feature branches with hundreds of new lines of code and it can seem daunting to implement a large feature in small stages. Trunk-based development is a system to handle large changes like this. It focuses on creating small PR and using tools such as feature flags. The following article from Atlassian does a great job discussing all the benefits of trunk-based development (i.e. impact on automated testing, having fewer active branches, and more): **[Atlassian Article](https://www.atlassian.com/continuous-delivery/continuous-integration/trunk-based-development)** Instead of using feature flags, one can also use the "branch by abstraction" method found in [this article](https://trunkbaseddevelopment.com/branch-by-abstraction/). This is similar to referencing an interface instead of a class and much like dependency inversion, can both increase or reduce the complexity of your code. From c91dd96f9bfeb8b2b6d3b40a4856e9976f788d6b Mon Sep 17 00:00:00 2001 From: WeissSa Date: Wed, 15 Nov 2023 18:08:55 -0500 Subject: [PATCH 4/5] updated with new picture/scenarios --- .../Development_Process/Trunk_Development.md | 24 +++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/Topics/Development_Process/Trunk_Development.md b/Topics/Development_Process/Trunk_Development.md index b17ec7808..bc5b9177f 100644 --- a/Topics/Development_Process/Trunk_Development.md +++ b/Topics/Development_Process/Trunk_Development.md @@ -1,5 +1,25 @@ ### Trunk-Based Development -Knowing how to manage the creation of large new features in your repository is an important skill, especially when working in large organizations or on projects with complete CI systems. It can be tempting to have large feature branches with hundreds of new lines of code and it can seem daunting to implement a large feature in small stages. Trunk-based development is a system to handle large changes like this. It focuses on creating small PR and using tools such as feature flags. The following article from Atlassian does a great job discussing all the benefits of trunk-based development (i.e. impact on automated testing, having fewer active branches, and more): **[Atlassian Article](https://www.atlassian.com/continuous-delivery/continuous-integration/trunk-based-development)** +Knowing how to manage the creation of large new features in your repository is an important skill, especially when working in large organizations or on projects with complete CI systems. It can be tempting to have large feature branches with hundreds of new lines of code and it can seem daunting to implement a large feature in small stages. Trunk-based development is a system to handle large changes like this. It focuses on creating small pull requests and using tools such as feature flags. The following article from Atlassian does a great job discussing all the benefits of trunk-based development (i.e. impact on automated testing, having fewer active branches, and more): **[Atlassian Article](https://www.atlassian.com/continuous-delivery/continuous-integration/trunk-based-development)** -Instead of using feature flags, one can also use the "branch by abstraction" method found in [this article](https://trunkbaseddevelopment.com/branch-by-abstraction/). This is similar to referencing an interface instead of a class and much like dependency inversion, can both increase or reduce the complexity of your code. +A picture that can help you visualize what trunk-based development might look like on a large team can be found at [trunkbaseddevelopment.com](https://trunkbaseddevelopment.com/) + +![Trunk Based Development Diagram](https://trunkbaseddevelopment.com/trunk1c.png) + +#### Feature Flags + +As mentioned above, feature flags are a fantastic tool to use when engaging in trunk-based development. The article above explains them abstractly, but a more concrete example might be: + +- Let's say you are working on a deployed website. You want to change the search algorithm but don't want to remove your old algorithm until your new one is finished. Because you are an excellent trunk-based developer, you decide to use feature flags! + +- You create your feature flag and set it to false. Then when coding your changes, you make sure that when the feature flag is false, all behaviour on your website remains the exact same. However, when you set your feature flag to true, your new feature becomes enabled. + +- Once your new search engine capability is fully ready, tested, and customer-approved, you enable your feature flag on deployment, and everyone gains access to it. + +Notice how in the above scenario, if the new feature breaks the deployment, all you have to do is turn your feature flag off again! + +#### Branching By Abstraction + +Instead of using feature flags, one can also use the "branch by abstraction" method found in [this article](https://trunkbaseddevelopment.com/branch-by-abstraction/). This is similar to referencing an interface instead of a class and much like dependency inversion, can both increase or reduce the complexity of your code. Using the same example by above, you might make a searchAlgorithmInterface, and have both your old and new algorithms implement it. + +It is up to the developer which method is better for a given situation. From ac2b6c76b0e8c2630aeb1450cce884840925d064 Mon Sep 17 00:00:00 2001 From: WeissSa Date: Wed, 15 Nov 2023 18:37:24 -0500 Subject: [PATCH 5/5] added clarification --- Topics/Development_Process/Trunk_Development.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Topics/Development_Process/Trunk_Development.md b/Topics/Development_Process/Trunk_Development.md index bc5b9177f..1f48c6854 100644 --- a/Topics/Development_Process/Trunk_Development.md +++ b/Topics/Development_Process/Trunk_Development.md @@ -14,7 +14,7 @@ As mentioned above, feature flags are a fantastic tool to use when engaging in t - You create your feature flag and set it to false. Then when coding your changes, you make sure that when the feature flag is false, all behaviour on your website remains the exact same. However, when you set your feature flag to true, your new feature becomes enabled. -- Once your new search engine capability is fully ready, tested, and customer-approved, you enable your feature flag on deployment, and everyone gains access to it. +- Once your new search engine capability is fully ready, tested, and customer-approved, you enable your feature flag on deployment, and everyone gains access to it. Once you are confident in your new feature, feel free to remove any code related to the old feature and then remove the feature flag (leaving the new feature as the only case in the code). Notice how in the above scenario, if the new feature breaks the deployment, all you have to do is turn your feature flag off again!