Update documentation.

Author: elibon99

README.adoc

@@ -0,0 +1,143 @@
+== GitBark Core
+A collection of useful rules and subcommands for use in link:https://github.com/YubicoLabs/gitbark[GitBark].
+
+=== Usage
+To use this package in GitBark include the package reference in the `requirements.txt` file, that should be located in the `bark_rules` branch (for more information see link:https://github.com/YubicoLabs/gitbark/blob/main/doc/Overview.adoc#bark-modules[here]). Below is an example:
+
+----
+# requirements.txt
+git+https://github.com/YubicoLabs/gitbark-core.git
+----
+
+The module can also be added interactively using the `bark add-modules` command.
+
+
+=== Commit Rules
+
+==== `require_signature`
+
+This rule mandates that a commit must be signed by a specific key, supporting both SSH and OpenPGP keys, including Security Keys.
+
+The authorized keys are defined as one or a list of glob patterns matching the specific public key files, which should be checked into the repository and reside in `/.bark/.pubkeys/`.
+
+Here is an example configuration of this rule in the `commit_rules.yaml` file:
+
+[source, yaml]
+----
+rules:
+- require_signature:
+    authorized_keys: [Alice.pub, Bob.pub]
+----
+In this configuration, only commits signed with Alice's or Bob's key are considered authorized.
+
+==== `file_not_modified`
+
+This rule prevents modification to specific fles.
+
+The set of files that should remain unmodified is defined as one or more glob patterns.
+
+An example configuration of this rule in the `commit_rules.yaml` file is shown below:
+
+[source, yaml]
+----
+rules:
+- file_not_modified:
+    pattern: sensitive.json
+----
+
+To achieve file-level authorization one can combine this rule with `require_signature` using the `any` clause (for more information on the `any` clause see link:https://github.com/YubicoLabs/gitbark/blob/main/doc/Overview.adoc#specification[here]).
+
+Here is an example of that configuration:
+
+[source, yaml]
+----
+rules:
+- any:
+    - file_not_modified:
+        pattern: sensitive.json
+    - require_signature:
+        authorized_keys: Alice.pub
+----
+In this configuration the two rules are evaluated using OR logic, meaning that at least one of them need to be satisfied. The resulting behavior stipulates that `sensitive.json` cannot be modified unless the commit is signed by Alice.
+
+==== `max_parents`
+This rule requires a commit to have a maximum number of parents.
+
+An example configuration of this rule in the `commit_rules.yaml` file is shown below:
+
+[source, yaml]
+----
+rules:
+- max_parents:
+    threshold: 1
+----
+In this configuration, the rule mandates that a commit can have a maximum of one parent.
+
+
+==== `require_valid_parents`
+By default, not all commits are required to be valid in GitBark. The framework only ensures that a commit is validated against the rules defined in the nearest **valid** ancestor commit.
+
+Using this rule you can reuire ALL parents of a commit to be valid, as seen below:
+
+[source, yaml]
+----
+rules:
+- require_valid_parents:
+----
+
+Optionally, you can allow non-valid parents as long as their commit hashes are included in the commit message (this makes allowing them more explicit, which prevent accidental inclusion). To accomplish this, use the `allow_explicit` parameter, as illustrated below:
+
+[source, yaml]
+----
+rules:
+- require_valid_parents:
+    allow_explicit: True
+----
+
+=== Ref Rules
+
+==== `require_approval`
+This rule requires commits on specific references to be **Approved** by a predetermined number of people.
+
+An **Approved** commit is a merge commit comprising a previous commit from the target ref, followed by one or more **Approval** commits. All its approval commits must have the same tree hash as the approved commit, and must include the approved commits initial parent in their set of parents. All approval commits must also have the same set of parents, and must be valid according to their commit rules.
+
+Essentially, an approval commit is a "normal" merge commit, with additional approvals being copies of the first approval, but with different authors (and possible messages). The *approved* commit is then an octo-merge commit containing the merge target, and all approval commits.
+
+To configure this rule, you must define the set of authorized approvers (as a list of email addresses) and the approval threshold.
+
+An example configuration of this rule in the `bark_rules.yaml` file is shown below:
+
+[source, yaml]
+----
+project:
+- bootstrap: 80a177b2b7fc39b4dd664fcda0cd185457fbaaeb
+  refs:
+  - pattern: refs/heads/main
+    rules:
+    - require_approval:
+        threshold: 2
+        authorized_authors:
+        - alice@test.com
+        - bob@test.com
+----
+This configuration requires the HEAD commit on `refs/heads/main` to be **Approved** by Alice and Bob.
+
+==== `require_fast_forward`
+This rule requires changes on specific references to be fast-forward only (i.e. no force pushing, linear history).
+
+An example configuration of this rule is shown below:
+
+[source, yaml]
+----
+project:
+- bootstrap: 80a177b2b7fc39b4dd664fcda0cd185457fbaaeb
+  refs:
+  - pattern: refs/heads/main
+    rules:
+    - require_fast_forward:
+----
+This configuration prevents non-fast-forward changes on `refs/heads/main`.
+
+
+
+

README.md

@@ -4,7 +4,7 @@ version = "0.1.0"
 description = "Core Bark rules and commands"
 authors = ["Elias Bonnici <elias.bonnici@yubico.com>"]
 license = "APACHE-2.0"
-readme = "README.md"
+readme = "README.adoc"
 packages=[{include = "bark_core"}]
 
 [tool.poetry.dependencies]