23 collaboration with git (#30)

* restructuring principles

* adding feature branch section

source/content/feature_branch/benefits.md

@@ -0,0 +1,8 @@
+{% if slide %}### Benefits{% endif %}
+
+:::{card}{% if page %} Benefits{% endif %}
+- Isolate changes and reduce conflicts
+- Enable parallel development and testing
+- Improve code quality and stability
+- Simplify merging and deployment
+:::

source/content/feature_branch/how_it_works.md

@@ -0,0 +1,11 @@
+{% if slide %}### How It Works{% endif %}
+
+:::{card}{% if page %} How It Works{% endif %}
+
+1. Create a new branch for a specific feature or change
+1. Apply the concept of a healthy reference to the feature branch
+1. Make incremental changes to the branch, testing and refining as needed
+1. Merge the branch into the main codebase when complete
+1. Repeat the process for each new feature or change
+
+:::

source/content/feature_branch/idea.md

@@ -0,0 +1,7 @@
+{% if slide %}### Idea{% endif %}
+
+:::{card}{% if page %} Idea{% endif %}
+
+Create a separate branch for each new feature or change, allowing for independent development and testing.
+
+:::

source/content/feature_branch/index.md

@@ -0,0 +1,38 @@
+# ✨Feature✨ Branch Approach
+{% if page %}
+This section presents one particular development approach with the aim to **introduce a development workflow that is both intuitive to follow and easy to implement.**
+
+However, there exists a plethora of approaches, more or less similar to this one and we recommend [Martin Fowler's blog about "Patterns for Managing Source Code Branches"](https://martinfowler.com/articles/branching-patterns.html) for anyone that is interested in learning more about them.
+
+Since we would like to provide an approach that can be used in most cases, we will describe the Feature Branch Approach somewhat loosely, in particular we will not insist of a clear definition of the term feature.
+
+In simple terms, the Feature Branch Approach describes:
+{% endif %}
+
+
+```{epigraph}
+How to manage and organize changes in a controlled and efficient way.
+```
+{% if page %}
+
+
+{% endif %}
+
+{% if build == "slides" %}
+<!-- BUILDING THE SLIDES -->
+```{toctree}
+:maxdepth: 1
+
+./idea
+./benefits
+./how_it_works
+```
+{% else %}
+<!-- BUILDING THE PAGES -->
+```{include} ./idea.md
+```
+```{include} ./benefits.md
+```
+```{include} ./how_it_works.md
+```
+{% endif %}

source/content/index.md

@@ -7,5 +7,7 @@ elements/index
 history/index
 commands/index
 update_cycle/index
+principles/index
+feature_branch/index
 exercise/index
 ```

source/content/principles/good_collaboration.md

@@ -0,0 +1,5 @@
+```{epigraph}
+The usage of <i class="fab fa-git"></i> does not necessarily facilitate collaboration.
+
+**It all depends on how you are using <i class="fab fa-git"></i>!**
+```

source/content/principles/healthy_reference.md

@@ -0,0 +1,27 @@
+## Healthy Reference
+
+> A pre-requirement to successfully develop any change, or new feature, is **to be able to depart from a functional state**.
+
+In the <i class="fab fa-git"></i>-context this translates to:
+
+**At any time all developers know of a specific commit on a specific branch that represents a healthy state**
+
+More precisely this state should:
+
+- contain most of the history, i.e. as recent as possible
+- have a minimal chance to contain errors
+- be functional
+
+{% if slide %}
+```{toctree}
+:maxdepth: 1
+:hidden:
+
+./healthy_reference_best
+```
+{% else %}
+A successful collaboration and development strategy should cultivate healthy states, leading to the first set of best practices:
+
+```{include} ./healthy_reference_best.md
+```
+{% endif %}

source/content/git/principles/healthy_reference_best.md → source/content/principles/healthy_reference_best.md

@@ -1,6 +1,5 @@
 ### Best Practice (1/4)
 
-A successful collaboration and development strategy should cultivate healthy states, leading to the first set of best practices:
 
 :::{card} Keep a healthy reference
 - Identify one branch on one location to be the main reference{% if page %}[^sn1]{% endif %}

source/content/principles/index.md

@@ -0,0 +1,38 @@
+# Collaboration Principles
+
+```{epigraph}
+The usage of <i class="fab fa-git"></i> does not necessarily facilitate collaboration.
+
+**It all depends on how you are using <i class="fab fa-git"></i>!**
+```
+
+{% if build == "slides" %}
+<!-- BUILDING THE SLIDES -->
+```{toctree}
+:maxdepth: 1
+:caption: Principles
+
+./healthy_reference
+./separate
+./steps
+./states
+```
+{% else %}
+<!-- BUILDING THE PAGES -->
+Even though with <i class="fab fa-git"></i> you can track and document strictly all changes in a repository, simply using <i class="fab fa-git"></i> does not yet make you a good collaborator.
+
+What exactly are good usage patterns is a well discussed and opinionated subject.
+
+Instead of contributing to this discussion we will point out a few principles that simplify interactions mediated by <i class="fab fa-git"></i>.
+
+```{include} ./healthy_reference.md
+```
+```{include} ./separate.md
+```
+```{include} ./steps.md
+```
+```{include} ./states.md
+```
+{% endif %}
+
+

source/content/principles/separate.md

@@ -0,0 +1,32 @@
+## Separate Changes
+
+> Any storyline is easier to follow if it is split into chapters. Chapters provide the option to organize, pace, and develop a narrative.
+
+A <i class="fab fa-git"></i> repository is no different:
+
+**Development should always be structured into  manageable, independent pieces allowing for focused work, clear boundaries, and easy integration into the larger whole.**
+
+
+{% if slide %}
+```{toctree}
+:maxdepth: 1
+:hidden:
+
+./separate_best
+```
+{% else %}
+Typically, **a repository contains various types of files** and **a developer performs various tasks**, like
+- adding new features
+- refactoring existing code
+- fixing typos
+- completing the documentation.
+- ...
+
+With <i class="fab fa-git"></i> any edit can lead to a commit and a branch can consist of any sequence of commits.
+It is up to the developer to associate branches with specific subjects or tasks and distribute commits onto these branches in a meaningful manner.
+
+Following the history of a repository becomes easier if the single branches incorporate some subject specificity, leading to a further set of best practices:
+
+```{include} ./separate_best.md
+```
+{% endif %}

source/content/git/principles/separate_best.md → source/content/principles/separate_best.md

@@ -1,9 +1,5 @@
 ### Best Practice (2/4)
 
-Following the history of a repository becomes easier if the single branches incorporate some subject specificity, leading to a further set of best practices:
-
-<!-- pages-include -->
-
 :::{card} Use branches to isolate changes
 - Agglomerate commits with a similar subject or purpose in a common branch
 - Incorporate branches with completed purpose

source/content/principles/states.md

@@ -0,0 +1,24 @@
+## Flag states
+
+> An easily distinguishable reference facilitates orientation.
+
+With <i class="fab fa-git"></i> this translates to:
+
+**Documenting states is equally important to documenting changes**
+
+
+{% if slide %}
+```{toctree}
+:maxdepth: 1
+:hidden:
+
+./states_best
+```
+{% else %}
+
+As a developer working the most noticeable _documentation_ activity is writing commit messages.
+As commit messages describe the introduced changes it can quickly become cumbersome to identify previous states. Essentially, when writing only <i class="fab fa-git"></i> commit messages **the state of a repository remains undocumented**.
+
+```{include} ./states_best.md
+```
+{% endif %}

source/content/git/principles/states_best.md → source/content/principles/states_best.md

@@ -1,9 +1,5 @@
 ### Best Practice (4/4)
 
-As a consequence it can become difficult to identify healthy states which is something that can be circumvented by the use of git tags:
-
-<!-- pages-include -->
-
 :::{card} Regularly tag good states
 - Tag particular states (see [**git tag**&nbsp;{octicon}`link-external;0.8em`](https://git-scm.com/docs/git-tag))
 - Use a meaningful versioning framework to describe states (e.g. [semver&nbsp;{octicon}`link-external;0.8em`](https://semver.org/))

source/content/principles/steps.md

@@ -0,0 +1,29 @@
+## Meaningful Steps
+
+> Incremental change is easier to deal with if single increments are logical, self-contained but remain as lean as possible.
+
+In the <i class="fab fa-git"></i>-world:
+
+**Incremental changes should introduced minimal, self-contained logical steps**
+
+
+{% if slide %}
+```{toctree}
+:maxdepth: 1
+:hidden:
+
+./steps_best
+```
+{% else %}
+It is up to the developer to decide how many or few edits go into a commit and, similarly to the [Separate subjects](#separate-subjects), what these changes are about.
+
+In addition, commits make up the elementary steps in a git history and can easily be:
+
+- undone (see e.g. [**git revert**&nbsp;{octicon}`link-external;0.8em`](https://git-scm.com/docs/git-revert))
+- applied onto other branches
+
+As a consequence it can become difficult to identify healthy states which is something that can be circumvented by the use of <i class="fab fa-git"></i> tags:
+
+```{include} ./steps_best.md
+```
+{% endif %}

source/content/git/principles/steps_best.md → source/content/principles/steps_best.md

@@ -1,9 +1,5 @@
 ### Best Practice (3/4)
 
-As a consequence we want to fill commits with just enough changes to perform a meaningful step and, therefore:
-
-<!-- pages-include -->
-
 :::{card} Commit small but complete changes
 - Decide what changes to include in a commit (use `git add -p`)
 - Make a commit as specific as possible