Develop Information Architecture

tgraham-ucsc commented 1 year ago

This ticket is intended to encapsulate the first iteration of our Information Architecture Documentation; it will have a number of sub-tasks to track individual topics that need documentation. Some of these documents have been started and will be available locally when you check out the doc-stage branch.

Supporting Issues:

[x] #21
[x] #22
[x] #19
[x] #23 🎓
[x] #24

Branching Strategy

For the doc repo the branching strategy changes slightly as the development environment takes place largely on the workstation. The branch doc-stage will serve as a staging branch where pull requests can be merged without approval, reviews will take place when merging to main. The reason behind this is to provide a stable branch that is available for a consolidated view prior to begin published.

---
title: Documentation Branching Strategy
---

%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showCommitLabel': false}} }%%
gitGraph
   commit
   commit
   branch doc-stage
   checkout doc-stage
   branch feature_1
   commit
   commit
   commit
   checkout doc-stage
   merge feature_1
   checkout doc-stage
   branch feature_2
   commit
   commit
   checkout doc-stage
   merge feature_2
   checkout main
   merge doc-stage
   commit
   commit

Change Branch Source

Our typical workflows have us branching from main, in this workflow, we're going to want to Change branch source; this option is available once you click Create a branch from the Development panel. The screenshot below illustrates what/where you want to create your development branch from.

insuhpak commented 1 year ago

(Might not be the appropriate ticket to track this -- I will move it if necessary.) Update doc repo readme to instruct downloading theme-mermaid?

jtomkins commented 1 year ago

The above workflow infers changes merging from the doc-stage branch back into main are coordinated but does not mention a process for how this will be handled.

Right now our team is small and the risk is low. I see a bigger problem in the future if they are not coordinated. I see a potential problem for the scenario where there are two features in the doc-stage branch, one is ready to go to production and one is not, if the doc-stage branch is merged to main without coordination the not ready changes will also merge to main.

If the idea is to use the doc-stage branch like a release branch, then will need to coordinate timing of when to branch from doc-stage and when to merge new changes into doc-stage .

If not I have two suggestions to help support grouping/coordinating changes. # 1 adds more overhead with branch management but might be more familiar with teams etc. and # 2 is more streamlined

introduce another branch -- release branch:
- requires coordinating releases and dates
- release branch separates and contains known/ready changes to merge to main
- development and testing can still continue using the doc-stage branch
- multiple features managed in the release branch
- Creating this branch starts the next release cycle, no new features can be added after this point—only bug fixes, and other release-oriented tasks should go in this branch.
consider streamlining the workflow like below:
- the feature branch is created from the main branch
- merge feature branch into the doc-stage branch to be used to locally review multiple changes as a consolidated view prior to begin published
- merge feature branch directly into main after User Acceptance Testing/QA via PR

To me feature branch development workflow is a lot of overhead and prefer # 2.

Something like this:

---
title: Documentation Branching Strategy
---

%%{init: { 'logLevel': 'debug', 'theme': 'base', 'gitGraph': {'showCommitLabel': false}} }%%
gitGraph
   commit
   branch doc-stage
   checkout main
   branch feature_1
   commit
   commit
   checkout main
   branch feature_2
   commit
   commit
   commit
   checkout doc-stage
   merge feature_1
   checkout main
   merge feature_1

   checkout feature_2
    commit
    merge main
    commit

   checkout doc-stage
   merge feature_2
   checkout main
   merge feature_2

   checkout doc-stage
   merge main

As a side note I came across Trunk Based development and am intrigued, I would be interested in learning more to figure out if it this is something that might work for our teams. Discussion 152

Trunk-based development

There are two main patterns for developer teams to work together using version control. One is to use feature branches, where either a developer or a group of developers create a branch usually from trunk (also known as main or mainline) and then work in isolation on that branch until the feature they are building is complete. When the team considers the feature ready to go, they merge the feature branch back to trunk.

The second pattern is known as trunk-based development, where each developer divides their own work into small batches and merges that work into trunk at least once (and potentially several times) a day. The key difference between these approaches is scope. Feature branches typically involve multiple developers and take days or even weeks of work. In contrast, branches in trunk-based development typically last no more than a few hours, with many developers merging their individual changes into trunk frequently

cdp-ucsc / doc