Contributing

glauth · Oct 7, 2023 · 7351e11 · 7351e11
1 parent 09b9e0f
commit 7351e11
Show file tree

Hide file tree

Showing 51 changed files with 3,196 additions and 90 deletions.
diff --git a/README.md b/README.md
@@ -52,3 +52,21 @@ yarn build
 
 See `.txt` files in `content/images/`
 
+## Markdown
+
+```
+[[toc]]
+
+::: wanrning
+blah
+:::
+
+Here is a footnote reference,[^1] and another.[^longnote]
+
+[^1]: Here is the footnote.
+
+[^longnote]: Here's one with multiple blocks.
+
+    Subsequent paragraphs are indented to show that they
+belong to the previous footnote.
+```
diff --git a/assets/style.css b/assets/style.css
diff --git a/docs/backends.html b/docs/backends.html
diff --git a/docs/building.html b/docs/building.html
diff --git a/docs/capabilities.html b/docs/capabilities.html
diff --git a/docs/compatibility.html b/docs/compatibility.html
diff --git a/docs/contact/index.html b/docs/contact/index.html
diff --git a/docs/containerization.html b/docs/containerization.html
diff --git a/docs/contributing.html b/docs/contributing.html
diff --git a/docs/custom-attributes.html b/docs/custom-attributes.html
diff --git a/docs/databases.html b/docs/databases.html
diff --git a/docs/debugging-ldap-behaviors.html b/docs/debugging-ldap-behaviors.html
diff --git a/docs/development.html b/docs/development.html
diff --git a/docs/docs/search-index.json b/docs/docs/search-index.json
diff --git a/docs/file.html b/docs/file.html
diff --git a/docs/high-availability.html b/docs/high-availability.html
diff --git a/docs/index.html b/docs/index.html
diff --git a/docs/kubernetes.html b/docs/kubernetes.html
diff --git a/docs/limitations.html b/docs/limitations.html
diff --git a/docs/logging.html b/docs/logging.html
diff --git a/docs/multifactor.html b/docs/multifactor.html
diff --git a/docs/mysql.html b/docs/mysql.html
diff --git a/docs/openldap-setup.html b/docs/openldap-setup.html
diff --git a/docs/openssh-keys.html b/docs/openssh-keys.html
diff --git a/docs/owncloud.html b/docs/owncloud.html
diff --git a/docs/postgresql.html b/docs/postgresql.html
diff --git a/docs/quickstart.html b/docs/quickstart.html
diff --git a/docs/rate-limiting.html b/docs/rate-limiting.html
diff --git a/docs/related-projects.html b/docs/related-projects.html
diff --git a/docs/rfcs-and-extensions.html b/docs/rfcs-and-extensions.html
diff --git a/docs/running-travis-ci-locally.html b/docs/running-travis-ci-locally.html
diff --git a/docs/s3.html b/docs/s3.html
diff --git a/docs/security.html b/docs/security.html
diff --git a/docs/setup.html b/docs/setup.html
diff --git a/docs/shipping-using-podman.html b/docs/shipping-using-podman.html
diff --git a/docs/sqlite.html b/docs/sqlite.html
diff --git a/docs/ssh-integration.html b/docs/ssh-integration.html
diff --git a/docs/ssh-libpam-ldap-ncsd.html b/docs/ssh-libpam-ldap-ncsd.html
diff --git a/docs/ssh-sssd.html b/docs/ssh-sssd.html
diff --git a/docs/style.css b/docs/style.css
diff --git a/docs/testing.html b/docs/testing.html
diff --git a/docs/web-ui.html b/docs/web-ui.html
diff --git a/docs/yubikey.html b/docs/yubikey.html
diff --git a/spacebook/content/pages/building.md b/spacebook/content/pages/building.md
@@ -10,8 +10,6 @@ eleventyNavigation:
 ---
 ## Make Targets
 
-Note - makefile uses git data to inject build-time variables. For best results, run in the context of the git repo.
-
 |Target|Description|
 |-|-|
 |*make all*|run build binaries for platforms|

diff --git a/spacebook/content/pages/contributing.md b/spacebook/content/pages/contributing.md
@@ -0,0 +1,101 @@
+---
+title: Contributing
+date: Last Modified
+permalink: contributing.html
+eleventyNavigation:
+  key: Contributing
+  parent: Development
+  order: 1109
+  title: Contributing
+---
+Starting with GLAuth 2.4.0, we have reworked and optimized the build workflow, and this starts with a new contribution process.
+
+[[toc]]
+
+# Preparing to Commit
+
+Format your code automatically using `gofmt -d ./` before committing. If you forget this step, a subsequent pull request may fail.
+
+# Writing Commit Messages
+
+Commit messages must be semantically correct; this is all conventions, of course, and the one that  has worked well for us is [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/)
+
+Here's the minimum information you need to know:
+
+A commit message contains a prefix, followed by a short explanation. It may also contain "footer" annotations, but these are not mandatory (albeit appreciated)
+
+Should you bundle multiple items in the same commit (say a new feature and a bug fix), you can... wait no please **don't do that.**
+
+## Commit Prefix
+
+A prefix is written imperatively and looks like this:
+```
+feat(plugins)!: Change the plugins API to allow NoSQL databases.
+```
+A quick decoding of this message reveals that this is a new feature (`feat`) and we **optionally** specify which area of GLAuth is impacted (`(plugins)`) - We also warn the reader of a breaking change (`!`)
+
+A more innocuous change could be:
+```
+chore: Add more comments in all modules.
+```
+
+Here is a pretty self-explanatory list of prefixes: `feat`, `fix`, `chore`, `build`, `ci`, `perf`, `refactor`, `test`, `style`
+
+## Commit Footer Annotations
+
+For instance:
+```
+Reviewed-by: John Romero <john@romero.com>
+Tested-by: Joel Spolsky <joel@joelonsoftware.com>
+BREAKING-CHANGE: I am yelling because I broke the plugin API compatibility!
+```
+
+_None of the people mentioned above were harmed in the writing of this example_
+
+Here is a far-from-exhaustive list of footer annotations:
+
+`Signed-Off-by`, `Acked-by`, `Reviewed-by`, `Helped-by`, `Co-authored by`, `Reported-by`, `Tested-by`, `Cc`, `Reference-to`, `See-also`, `BREAKING-CHANGE`
+
+# Pull Requests
+
+## Creating a Pull Request
+
+Create your Pull Requests from your branch directly to the **'Master'** branch. We discontinued use of the 'Dev' branch as we wish to enforce pulling from tagged versions, as opposed to making the merge flow more difficult to follow by jumping through intermediate branches.
+
+## Merging a Pull Request
+
+If you have the privileges to merge a pull request, please start by ensuring that it follows the proper conventions.
+
+::: callout-blue
+Note that pull requests that represent branch merges and other maintenance operations should not, in fact, follow these conventions. This allows us to exclude them from a release's notes.
+:::
+
+# Releasing
+
+## Versioning
+
+We follow the [Semantic Version v2.0 conventions](https://semver.org/)
+
+Therefore, all releases follow this numbering scheme: **v&lt;major&gt;.&lt;minor&gt;.&lt;patch&gt;**, e.g. 'v1.1.0'
+
+- The patch number increments as we add bug fixed or minor tweaks
+- The minor number increments as we make significant changes, such as code refactoring
+- An increment of the major number denotes a breaking change!
+
+::: callout
+You may submit an important feature that we all want to incorporate in GLAuth quickly. However, we cannot surprise our users by breaking their production setups. Therefore, we have to strike a balance between our desire to release the feature, and the need to wait for a major release to do so.
+:::
+
+## Creating a Release
+
+We now rely on [release-please](https://github.com/google-github-actions/release-please-action) to automate the creation of release notes based on semantically correct commits (see above)
+
+Any commit message following the proper conventions will be included in the release notes, while "housekeeping" commits will not be.
+
+To create a new release, in this example 2.0.0:
+
+```
+git commit --allow-empty -m "chore: release 2.0.0" -m "Release-As: 2.0.0"
+```
+
+The 'release-please' action will create a Pull Request tracking all commits since the last release tag.
diff --git a/spacebook/content/pages/databases.md b/spacebook/content/pages/databases.md
@@ -10,7 +10,9 @@ eleventyNavigation:
 ---
 Various databases can be used as long as they implement the database plugin interfaces.
 
-Database Tables (scroll down for complete schema):
+[[toc]]
+
+Database Tables (scroll down for complete schema and discussion):
 
 |Name|Function|
 |-|-|
@@ -60,6 +62,92 @@ INSERT INTO capabilities(userid, action, object)
   VALUES(5003, "search", "*");
 ```
 
+This should be equivalent to this configuration:
+```toml
+[[users]]
+  name = "hackers"
+  uidnumber = 5001
+  primarygroup = 5501
+  passsha256 = "6478579e37aff45f013e14eeb30b3cc56c72ccdc310123bcdf53e0333e3f416a" # dogood
+    [[users.capabilities]]
+    action = "search"
+    object = "ou=superheros,dc=glauth,dc=com"
+
+[[users]]
+  name = "johndoe"
+  uidnumber = 5002
+  primarygroup = 5502
+  passsha256 = "6478579e37aff45f013e14eeb30b3cc56c72ccdc310123bcdf53e0333e3f416a" # dogood
+
+[[users]]
+  name = "serviceuser"
+  mail = "serviceuser@example.com"
+  uidnumber = 5003
+  passsha256 = "652c7dc687d98c9889304ed2e408c74b611e86a40caa51c4b43f1dd5913c5cd0" # mysecret
+  primarygroup = 5502
+    [[users.capabilities]]
+    action = "search"
+    object = "*"
+
+[[users]]
+  name = "user4"
+  uidnumber = 5003
+  primarygroup = 5504
+  othergroups = [5505, 5506]
+  passsha256 = "652c7dc687d98c9889304ed2e408c74b611e86a40caa51c4b43f1dd5913c5cd0" # mysecret
+    [[users.customattributes]]
+    employeetype = ["Intern", "Temp"]
+    employeenumber = [12345, 54321]
+
+[[groups]]
+  name = "superheros"
+  gidnumber = 5501
+
+[[groups]]
+  name = "svcaccts"
+  gidnumber = 5502
+
+[[groups]]
+  name = "civilians"
+  gidnumber = 5503
+  includegroups = [ 5501 ]
+
+[[groups]]
+  name = "caped"
+  gidnumber = 5504
+  includegroups = [ 5502, 5501 ]
+```
+
+and LDAP should return these `memberOf` values:
+
+```text
+uid: hackers
+ou: superheros
+memberOf: cn=caped,ou=groups,dc=militate,dc=com
+memberOf: cn=civilians,ou=groups,dc=militate,dc=com
+memberOf: cn=superheros,ou=groups,dc=militate,dc=com
+
+uid: johndoe
+ou: svcaccts
+memberOf: cn=caped,ou=groups,dc=militate,dc=com
+memberOf: cn=svcaccts,ou=groups,dc=militate,dc=com
+
+uid: serviceuser
+ou: caped
+memberOf: cn=caped,ou=groups,dc=militate,dc=com
+
+uid: user4
+ou: caped
+memberOf: cn=caped,ou=groups,dc=militate,dc=com
+memberOf: cn=lovesailing,ou=groups,dc=militate,dc=com
+memberOf: cn=smoker,ou=groups,dc=militate,dc=com
+```
+If you have the ldap client package installed, this can be easily confirmed by running
+```
+ldapsearch  -H ldap://localhost:3893 -D cn=hackers,ou=superheros,dc=glauth,dc=com -w dogood -x -bdc=glauth,dc=com cn=hackers
+```
+and so on.
+
 ## Database Schema 
 
 ![http://localhost:8000/docs/content/images/glauth-simple-schema.png](/docs/content/images/glauth-simple-schema.png)
@@ -117,4 +205,20 @@ _this table is used to retrieve capabilities granted to users linked to it from
 |id|internal id number, used by glauth|
 |userid|internal user id number, used by glauth|
 |action|string representing an allowed action, e.g. "search"|
-|object|string representing scope of allowed action, e.g. "ou=superheros,dc=glauth,dc=com"|
+|object|string representing scope of allowed action, e.g. "ou=superheros,dc=glauth,dc=com"|
+
+### Discussion: database schema
+
+While GLAuth is not meant to support millions of user accounts, some decent performance is still expected! In fact, when searching through records using a database query, we should see a performance of O(log n) as opposed to, when searching through a flat config, O(n).
+
+While it would be friendlier to offer related attributes in `join`ed tables, we may end up re-creating a "browse" scenario unintentionally.
+
+For instance, when retrieving custom attributes, we could go through an attribute table: `custattr[userid, attribute, value#n]`
+
+However, this means that a `join` statement between the account table and the custom attribute table would yield the cartesian product of each account x attributes; we would need to iterate through the results and collate them.
+
+Alternatively, in Postgres and MySQL, we could rely on the database engine's built-in support for `crosstab` which pivots the second table's results into corresponding columns. This would not be supported in SQLite and would also mean building pretty nasty execution plans.
+
+**So, what's the decision?**
+
+In GLAuth 2.x, when including information that does not benefit from being normalized (e.g. custom attributes) we are following the "nosql" trend (irony!) of storing this data in a JSON structure.
diff --git a/spacebook/content/pages/debugging-ldap-behaviors.md b/spacebook/content/pages/debugging-ldap-behaviors.md
@@ -5,7 +5,7 @@ permalink: debugging-ldap-behaviors.html
 eleventyNavigation:
   key: Debugging-LDAP
   parent: Development
-  order: 1110
+  order: 1115
   title: Debugging LDAP Behaviors
 ---
 ## Understanding LDAP filters

diff --git a/spacebook/content/pages/development.md b/spacebook/content/pages/development.md
@@ -12,6 +12,8 @@ You may find this section interesting if you are either:
 - helping test or document GLAuth
 - writing a third-party tool
 
+[Building](building.html)
+
 [Logging](logging.html)
 
 [Testing](testing.html)
@@ -26,5 +28,4 @@ You may find this section interesting if you are either:
 
 ## Contributing
 
-- Please base all Pull Requests on [dev](https://github.com/glauth/glauth/tree/dev), not master.
-- Format your code autonmatically using `gofmt -d ./` before committing
+Contributing now has its own [documentation](contributing.html)
diff --git a/spacebook/content/pages/logging.md b/spacebook/content/pages/logging.md
@@ -5,7 +5,7 @@ permalink: logging.html
 eleventyNavigation:
   key: Logging
   parent: Development
-  order: 1108
+  order: 1111
   title: Logging
 ---
 ## Logging Levels

diff --git a/spacebook/content/pages/quickstart.md b/spacebook/content/pages/quickstart.md
@@ -21,3 +21,7 @@ ldapsearch -LLL -H ldap://localhost:3893 \
    -D cn=serviceuser,ou=svcaccts,dc=glauth,dc=com -w mysecret \
    -x -bdc=glauth,dc=com cn=hackers
 ```
+
+## Databases
+
+To get started with one of the supported database engines, please follow [this link](databases.html) :toolbox:
diff --git a/spacebook/content/pages/testing.md b/spacebook/content/pages/testing.md
@@ -5,7 +5,7 @@ permalink: testing.html
 eleventyNavigation:
   key: Testing
   parent: Development
-  order: 1109
+  order: 1113
   title: Testing
 ---
 A core set of tests is being run by Github Actions CI. However, when developing new features/refactoring, a more comprehensive regression testing suite is needed.