Add code organization section and update feature flag & permission gu…

…ides (#93)

Co-authored-by: Robin Sund <[email protected]>

README.md

@@ -51,9 +51,9 @@ do not cover your particular topic, review their guides for guidance.
 
 - [Authorization](authorization/README.md)
 - [Change Requests](change-requests/README.md)
+- [Code Design](code-design/README.md)
 - [Data Changes](data-changes/README.md)
 - [Feature Flags](feature-flags/README.md)
-- [Object-Oriented Design](object-oriented-design/README.md)
 - [Web Monitoring](web-monitoring/README.md)
 
 ## Testing

authorization/README.md

@@ -7,13 +7,17 @@
   represents `create:donor` `read:donor` `update:donor` `delete:donor`.
 - Don't update roles or permissions directly within Auth0.
 - Use Terraform in the [DevOps] repository to update permissions.
-- Ensure the [Permissions Matrix] is up to date.
+- Ensure new permissions added in Terraform have detailed descriptions. Our customers need
+  to understand what the permission grants access to so they can properly manage roles.
+- Ensure new customer facing permissions are added to the `app/policies/permission_policy.rb`
+  allow list or they will not be visible to manage in roles and permission.
+- Prefer conditionally adding new permissions to allow list based on the feature flag.
 - Ensure permissions are updated in all Auth0 tenants.
   - Current tenants include: Development, Staging, Validation and Production
   - Non-breaking changes can be rolled out to all environments at the same time
   - Breaking changes need to be rolled out as the affected code moves to new environments
-- Ensure that a CHANGELOG entry has been added in Notion for the permissions
-  update.
+- Ensure that a CHANGELOG entry has been added to the [Permission Change Log] in Notion for
+  the permissions update.
 - The introduction of a new role is a non-breaking change that may be surprising to
   JoinParachute, ping Luke Winter and Erin Galarza
 - Ensure permission changes are documented in Asana. The transparency helps
@@ -26,7 +30,7 @@
 
 [DevOps]: https://github.com/BuoySoftware/DevOps
 [Four Eyes Principle]: https://www.openriskmanual.org/wiki/Four_Eyes_Principle
-[Permissions Matrix]: https://www.notion.so/0b902ab8e86e4f158772d2939837365e?v=f84d5f6e8cd04ff3a3c2b1b41c53404c
+[Permission Change Log]: https://www.notion.so/Permissions-Change-Log-4d85a45f8bba41a99b16540f150285d4
 
 ## Pundit Policies
 

object-oriented-design/README.md → code-design/README.md

@@ -1,10 +1,26 @@
-# Object-Oriented Design
+# Code Structure
+
+## Packwerk
+
+At Buoy we utilize [packwerk] to enable us to organize our code into
+packages based on domain concepts or business flows.
+
+### Guide
+
+- Prefer creating packs to encompass business flows (i.e. Processing, Payments).
+- Prefer adding pack specific models and concerns inside the pack if possible.
+- Prefer setting stewards.
+- Avoid creating team based packs.
+
+[packwerk]: https://github.com/Shopify/packwerk
+
+## Object-Oriented Design
 
 - Avoid global variables.
 - Avoid long parameter lists.
 - Limit dependencies of an object (entities an object depends on).
 - Limit an object's dependents (entities that depend on an object).
-- [Prefer composition over inheritance.]
+- [Prefer composition over inheritance].
 - Prefer small methods. Between one and five lines is best.
 - Prefer small classes with a single, well-defined responsibility. When a class
   exceeds 100 lines, it may be doing too many things.

feature-flags/README.md

@@ -17,7 +17,15 @@ of 3 categories:
 - For configuration toggles, prefer environment variable backed feature flags
 - Avoid creating feature flags with LaunchDarkly. This is considered deprecated
   unless used in React during our transition away from React.
-- Prefer using a feature flag when implementing a change which impacts SOPs.
+- Prefer using feature flags by default unless there's a compelling reason not to.
+  - Examples for feature flag use:
+    - SOPs are impacted
+    - Training required
+    - Release flexibility
+  - Examples where feature flags <b>may not</b> be needed:
+    - Added logging
+    - Date format changes
+- Prefer using data migrations to add new feature flags, defaulted to false.
 - Prefer a feature flag to a [feature branch].
 - Once a release toggle feature is turned on in production, create an Asana task in your
   project's respective project to remove the feature. Schedule it 1 week out to