diff --git a/docs/tut1.md b/docs/tut1.md index 120db9f..2d0532a 100644 --- a/docs/tut1.md +++ b/docs/tut1.md @@ -64,9 +64,9 @@ git add --all dehub commit --as tut change ``` -Like when you made a comment commit this will pop up with your editor asking for -a description of the changes. Fill it in with something like `Initialize the -project` and save/close the editor. Depending on your pgp key settings you'll +Like when you made a comment commit, this will pop up with your editor asking +for a description of the changes. Fill it in with something like `Initialize the +project` and save+close the editor. Depending on your pgp key settings you'll likely be prompted for your pgp key password at this point. After that the commit has been created! diff --git a/docs/tut2.md b/docs/tut2.md index 45e6a12..b2c7a45 100644 --- a/docs/tut2.md +++ b/docs/tut2.md @@ -68,20 +68,21 @@ dehub commit --as tut change --descr 'add new restricted tot account' ### Access Controls -Each access control is an action/filters pair. For any commit being verified, +Each access control is an action+filters pair. For any commit being verified, the access controls defined in its parent commit are iterated through, in order, until one is found whose filters all match the commit being verified. The action for that access control, either `allow` or `deny`, is then taken. If no access controls are defined, or none match, then the default access -controls are used. These are explicitly defined in the [SPEC](SPEC.html), but -the general effect of them is to require that all commits have one signature -from any of the project's accounts. +controls are used. These are explicitly defined in the +[SPEC](SPEC.html#default-access-controls), but the general effect of them is to +require that all commits have one signature from any of the project's accounts. ### Access Control Filters There are many different filter types, so only the ones used in the tutorial -will be explained. An exhaustive listing can be found in the [SPEC](SPEC.html). +will be explained. An exhaustive listing can be found in the +[SPEC](SPEC.html#filter). The `signature` filter matches commits which have a signature credential created by any one of the specified accounts. The `files_changed` filter matches commits @@ -149,13 +150,15 @@ dehub commit --as tot change --descr 'tut is a butt' ``` Somewhat unexpectedly, the commit has been created! You can see it by doing `git -show`. Is dehub broken? +show`. This shouldn't be possible though, because the previous commit disallowed +anyone but `tut` from changing files within the `.dehub/` directory. Is dehub +broken? The fact is that, regardless of whether or not the `dehub` tool allows one to -create this commit, `tut` can create this commit. The important thing is that -`tot` is able to notice that it's been created and do something about it. In a +create this commit, `tot` can create this commit. The important thing is that +`tut` is able to notice that it's been created and do something about it. In a real-world situation, both `tot` and `tut` would be using different computers, -and when `tot` (or anyone else) receives the commit from `tut` they will try to +and when `tut` (or anyone else) receives the commit from `tot` they will try to verify it, fail to do so, and ignore it. If you perform `dehub verify` you will be greeted with the following error: @@ -246,7 +249,7 @@ Running `dehub verify` now should fail, even though the commit remains the same. The only difference is the branch name; the commit is allowed in branches with the prefix `tot/`, and disallowed otherwise. -Finally, reverse that cherry-pick to make main verifiable again: +Finally, reverse that cherry-pick to make `main` verifiable again: ``` git reset --hard "$(git rev-list HEAD | tail -4 | head -n1)" diff --git a/docs/tut3.md b/docs/tut3.md index 24e494e..4962206 100644 --- a/docs/tut3.md +++ b/docs/tut3.md @@ -94,8 +94,7 @@ filter, such that this access control will match only if the commit _does not_ have signature credentials from 2 different accounts. The total effect of this access control is to deny any commits to `main` which -do not have signature credentials from 2 different accounts. In effect, commit -sign-off. +have not been signed-off by 2 different accounts. ## Step 1: Some Changes to Merge @@ -187,7 +186,7 @@ credentials: account: tut ``` -There is now enough credentials to combine both commits in the `tot/echo-script` +There are now enough credentials to combine the commits in the `tot/echo-script` branch into a single commit on the `main` branch. ## Step 3: Combination