Skip to content

Commit f2d890a

Browse files
elibon99elibon99
committed
Update documentation
1 parent f4247fb commit f2d890a

File tree

6 files changed

+350
-195
lines changed

6 files changed

+350
-195
lines changed

‎README.adoc

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
== GitBark
2+
3+
A framework that validates commits based on a set of fully customizable rules. This tool empowers you to enforce specific conditions, ensuring the integrity and adherence of your commits to project standards. Explore GitBark to elevate the validation process for a more robust and reliable version control workflow.
4+
5+
**NOTE: This is work in progress**
6+
7+
=== License
8+
9+
....
10+
Copyright 2024 Yubico AB
11+
12+
Licensed under the Apache License, Version 2.0 (the "License");
13+
you may not use this file except in compliance with the License.
14+
You may obtain a copy of the License at
15+
16+
http://www.apache.org/licenses/LICENSE-2.0
17+
18+
Unless required by applicable law or agreed to in writing, software
19+
distributed under the License is distributed on an "AS IS" BASIS,
20+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
21+
See the License for the specific language governing permissions and
22+
limitations under the License.
23+
....
24+
25+
[#installation]
26+
=== Installation
27+
Currently GitBark can only be installed from source using the following command:
28+
29+
pip install "git+https://github.com/YubicoLabs/gitbark.git
30+
31+
=== Usage
32+
Read the link:doc/Usage.adoc[Usage Guide] for instructions on how to use GitBark.
33+
34+
=== Documentation
35+
Read the link:doc/Overview.adoc[Overview] for a more comprehensive overview of GitBark.

‎README.md

-191
This file was deleted.

‎doc/Overview.adoc

+147
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
== Overview
2+
This document provides a comprehensive overview of GitBark and its components, and how they can be used to ensure the integrity of source code repositories. For a quick guide on how to get started, refer to our link:Usage.adoc[Usage Guide].
3+
4+
== Table of Contents
5+
6+
* <<Commit Rules>>
7+
* <<Bark Rules>>
8+
* <<Bark Modules>>
9+
* <<Git Hooks>>
10+
11+
[#commit-rules]
12+
=== Commit Rules
13+
Commit rules can be thought of as a set of conditions that a commit must meet to be considered valid. This section explores the concept of commit rules and their implementation and usage within GitBark.
14+
15+
==== Implementation
16+
Technically, commit rules are functions that operate on commit objects, potentially raising an exception to indicate whether the commit satisfies specified rule conditions. These functions are implemented in Python modules, referred to as Bark Modules. Serving as self-contained units, these modules encapsulate the behavior of one or more rules and reside outside GitBark, typically in Git repositories or on PyPI. They can be seamlessly integrated into GitBark for rule evaluation (refer to <<Bark Modules>> for more details).
17+
18+
While developers have the flexibility to create custom commit rules, we have pre-built a Bark Module called (link:https://github.com/YubicoLabs/gitbark-core[GitBark Core]), encompassing a collection of useful rules ready for immediate use.
19+
20+
[#specification]
21+
==== Specification
22+
To define the commit rules applicable to commits, developers must specify them in `/.bark/commit_rules.yaml`, which should be checked into the repository. Since this file is under version control, every commit points to a specific version of the `commit_rules.yaml` file (more on why this is important is described in the upcoming sections).
23+
24+
The `commit_rules.yaml` file follows a specific structure with a list of rules. Each rule may have optional parameters as described below:
25+
26+
[source, yaml]
27+
----
28+
rules:
29+
- rule_name_1:
30+
parameter1: value1
31+
parameter2: value2
32+
- rule_name_2:
33+
# No parameters for rule_name_2
34+
- rule_name_3:
35+
parameter1: value1
36+
parameter2: value2
37+
parameter3: value3
38+
----
39+
The `rule_name` serves as the identifier for the rule defined in the corresponding Bark Module. The same principle applies to `parameter`; some rules support parameters while others do not, depending on the implementation.
40+
41+
By default, all rules in the outer `rules` clause are validated using AND logic (all rules need to be satisfied). However, one can use the `any` clause to create more complex rule patterns. Rules defined in this clause are validated using OR logic (at least one of the rules need to be satisfied). See example below:
42+
43+
[source, yaml]
44+
----
45+
rules:
46+
- commit_rule_name_1:
47+
parameter1: value1
48+
parameter2: value2
49+
- any:
50+
- commit_rule_name_2:
51+
# No parameters for rule_name_2
52+
- commit_rule_name_3:
53+
parameter1: value1
54+
parameter2: value2
55+
parameter3: value3
56+
----
57+
58+
==== Validation
59+
A commit is considered valid if it passes the rules defined in its "nearest" **valid** ancestor commits. We call these commits **validators**, which are the commits that define the rules that a new commit should be validated against. The **validators** for a commit **c** are chosen the following way:
60+
61+
* If the parent of **c** itself is valid, the parent becoms a **validator** for **c**.
62+
* If the parent of **c** is not valid, **c** inherits all **validators** that the parent has.
63+
64+
Once the validator commits are collected, the commit rules defined in them are applied to the commit being validated. The commit is considered valid if it passes **ALL** these rules.
65+
66+
[#bootstrap]
67+
===== Bootstrap
68+
Since validation follows a recursive pattern, at some point we will reach a commit that does not have any parents or has parents that do not define any rules. This presents a bootstrapping issue which we solve using a bootstrap commit, that define the initial rules for a branch and is explicitly trusted and considered valid. Bootstrap commits for specific branches are defined in <<Bark Rules>>.
69+
70+
[#bark-rules]
71+
=== Bark Rules
72+
Bark Rules are repository-specific and define the configuration for validating specific branches, specifying conditions and criteria for the validation process. This configuration is encapsulated within a file named `/.bark/bark_rules.yaml`, which is committed to an orphaned branch named `bark_rules`.
73+
74+
[#bark-rules-specification]
75+
==== Specification
76+
The `bark_rules.yaml` file adheres to a structured format wherein bootstrap commits are associated with specific references, identified through a regex pattern match. This mechanism informs GitBark about which references (typically branches) to validate, using the designated bootstrap commit. The example below illustrates that `refs/heads/main` is configured for validation, with commit `8bd6128c239e1735858927af6cc91a8cf46c1924` as the designated bootstrap commit.
77+
78+
[source, yaml]
79+
----
80+
project:
81+
- bootstrap: 8bd6128c239e1735858927af6cc91a8cf46c1924
82+
refs:
83+
- pattern: refs/heads/main
84+
----
85+
86+
Besides specifying what branches should be validated using a specific bootstrap commit, the `bark_rules.yaml` file also allows us to define <<Ref Rules>>.
87+
88+
[#ref-rules]
89+
===== Ref Rules
90+
Ref Rules are rules tailored for specific references (branches). In contrast to Commit Rules, which are not reference-specific, Ref Rules exclusively apply to the commits a particular reference points to. This distinction enables the definition of distinct rules for various references, as exemplified in the `bark_rules.yaml` file below.
91+
92+
[source, yaml]
93+
----
94+
project:
95+
- bootstrap: 8bd6128c239e1735858927af6cc91a8cf46c1924
96+
refs:
97+
- pattern: refs/heads/main
98+
rules:
99+
- ref_rule_name_1:
100+
parameter1: value1
101+
- ref_rule_name_2:
102+
- pattern: refs/heads/feat
103+
rules:
104+
- ref_rule_name_3:
105+
parameter3: value3
106+
----
107+
108+
Ref Rules can also be defined for the `bark_rules` branch itself by including them in the `bark_rules` clause, as shown below:
109+
110+
[source, yaml]
111+
----
112+
bark_rules:
113+
- ref_rule_name_1:
114+
parameter1: value1
115+
project:
116+
...
117+
----
118+
119+
[#root-of-trust]
120+
==== Root of trust
121+
Since the `bark_rules.yaml` file among other things defines what bootstrap commits should be used to validate different branches, it is essential to protect the integrity of the `bark_rules` branch itself. As such, the `bark_rules` branch can have Commit Rules itself that are validated using the root commit (of the `bark_rules` branch) as bootstrap. All other bootstrap commits for commit validation are covered by this bootstrap commit. As such, when the system is initialized, the user is asked to confirm the hash of this commit (like when connecting to an SSH server the first time), as illustrated below.
122+
123+
----
124+
$ bark install
125+
The bootstrap commit (7b54840ecd6a484ec78314ff32e57fb38b4769bb) of the bark_rules branch has not been verified!
126+
Do you want to trust this commit as the bootstrap for bark? [y/N]:
127+
----
128+
129+
[#bark-modules]
130+
=== Bark Modules
131+
132+
Commit Rules and Ref Rules are implemented as Python modules or packages, referred to as 'Bark Modules.' These modules reside outside of GitBark, typically hosted in Git repositories or available on PyPI. To utilize specific Commit Rules and Ref Rules, it is necessary to specify which Bark Modules to employ. This configuration is accomplished in the `bark_rules` branch within the `requirements.txt` file, adhering to the standard pip requirements file. When specified GitBark installs the specific modules in a virtual environment residing in the repository, so that they can be used during validation.
133+
134+
Here is an example requirements file including link:https://github.com/YubicoLabs/gitbark-core[GitBark Core] as a Bark Module:
135+
136+
----
137+
git+https://github.com/YubicoLabs/gitbark-core.git
138+
----
139+
140+
=== Git Hooks
141+
Upon receiving updates to the local repository, commonly triggered by actions such as `git pull`, `git commit`, and `git push`, GitBark offers automated verification in alignment with the specified rules. This seamless process is made possible through the integration of client-side Git hooks. This way, rules can be enforced securely across repository clones without needing to trust intermediate clones. For example, a team of developers may enforce specific rules on their local clones even if a central Git hosting service does not yet support enforcing those rules, and may allow updates that violate those rules. The local clones will always remain in a consistent and trustworthy state in relation to established rules.
142+
143+
While this particular functionality isn't enabled by default, we strongly recommend enabling it to ensure the repository consistently maintains a trustworthy and consistent state. Achieve this by executing the `bark install` command, which effortlessly installs the essential Git hooks.
144+
145+
146+
147+

0 commit comments

Comments
 (0)