[doc] fix links, format

CODE_OF_CONDUCT.md

@@ -4,66 +4,66 @@
 
 ## Conduct
 
-* We are committed to providing a friendly, safe and welcoming environment for
-all, regardless of level of experience, gender identity and expression, sexual
-orientation, disability, personal appearance, body size, race, ethnicity, age,
-religion, nationality, or other similar characteristic.
+- We are committed to providing a friendly, safe and welcoming environment for
+  all, regardless of level of experience, gender identity and expression, sexual
+  orientation, disability, personal appearance, body size, race, ethnicity, age,
+  religion, nationality, or other similar characteristic.
 
-* Please be kind and courteous. There's no need to be mean or rude.
+- Please be kind and courteous. There's no need to be mean or rude.
 
-* Respect that people have differences of opinion and that every design or
-implementation choice carries a trade-off and numerous costs. There is seldom a
-right answer.
+- Respect that people have differences of opinion and that every design or
+  implementation choice carries a trade-off and numerous costs. There is seldom a
+  right answer.
 
-* Please keep unstructured critique to a minimum. If you have solid ideas you
-want to experiment with, make a fork and see how it works.
+- Please keep unstructured critique to a minimum. If you have solid ideas you
+  want to experiment with, make a fork and see how it works.
 
-* We will exclude you from interaction if you insult, demean or harass anyone.
-That is not welcome behavior. We interpret the term "harassment" as including
-the definition in the <a href="http://citizencodeofconduct.org/">Citizen Code of
-Conduct</a>; if you have any lack of clarity about what might be included in
-that concept, please read their definition. In particular, we don't tolerate
-behavior that excludes people in socially marginalized groups.
+- We will exclude you from interaction if you insult, demean or harass anyone.
+  That is not welcome behavior. We interpret the term "harassment" as including
+  the definition in the <a href="http://citizencodeofconduct.org/">Citizen Code of
+  Conduct</a>; if you have any lack of clarity about what might be included in
+  that concept, please read their definition. In particular, we don't tolerate
+  behavior that excludes people in socially marginalized groups.
 
-* Private harassment is also unacceptable. No matter who you are, if you feel
-you have been or are being harassed or made uncomfortable by a community member,
-please raise an issue immediately. Whether you're a regular contributor or a
-newcomer, we care about making this community a safe place for you and we've got
-your back.
+- Private harassment is also unacceptable. No matter who you are, if you feel
+  you have been or are being harassed or made uncomfortable by a community member,
+  please raise an issue immediately. Whether you're a regular contributor or a
+  newcomer, we care about making this community a safe place for you and we've got
+  your back.
 
-* Likewise any spamming, trolling, flaming, baiting or other attention-stealing
-behavior is not welcome.
+- Likewise any spamming, trolling, flaming, baiting or other attention-stealing
+  behavior is not welcome.
 
 ## Moderation
 
 These are the policies for upholding our community's standards of conduct. If
 you feel that a thread needs moderation, feel free to raise an issue here.
 
 1. Remarks that violate the standards of conduct, including hateful, hurtful,
-oppressive, or exclusionary remarks, are not allowed. (Cursing is allowed,
-but never targeting another user, and never in a hateful manner.)
+   oppressive, or exclusionary remarks, are not allowed. (Cursing is allowed,
+   but never targeting another user, and never in a hateful manner.)
 
 2. Remarks that moderators find inappropriate, whether listed in the code of
-conduct or not, are also not allowed.
+   conduct or not, are also not allowed.
 
 3. Moderators will first respond to such remarks with a warning.
 
 4. If the warning is unheeded, the user will be "kicked," i.e., kicked out of
-the communication channel to cool off.
+   the communication channel to cool off.
 
 5. If the user comes back and continues to make trouble, they will be banned,
-i.e., indefinitely excluded.
+   i.e., indefinitely excluded.
 
 6. Moderators may choose at their discretion to un-ban the user if it was a
-first offense and they offer the offended party a genuine apology.
+   first offense and they offer the offended party a genuine apology.
 
 7. If a moderator bans someone and you think it was unjustified, please take it
-up with that moderator, or with a different moderator, **in private**.
-Complaints about bans in-channel are not allowed.
+   up with that moderator, or with a different moderator, **in private**.
+   Complaints about bans in-channel are not allowed.
 
 8. Moderators are held to a higher standard than other community members. If a
-moderator creates an inappropriate situation, they should expect less leeway
-than others.
+   moderator creates an inappropriate situation, they should expect less leeway
+   than others.
 
 We strive to go the extra step to look out for each other. Don't just aim to be
 technically unimpeachable, try to be your best self. In particular, avoid

CONTRIBUTING.md

@@ -17,7 +17,8 @@ There are a few forms in the project which are not a part of the style guide but
 The recommended formatter is [cljfmt](https://github.com/weavejester/cljfmt) and the code formatting rules can be found in [.cljfmt.edn](/.cljfmt.edn)
 
 ## Use of Git
-* Avoid plain `git merge`, and use rebasing instead, to avoid merge commits. This keeps the history much more readable for others to understand, review bisect and rollback.
-* When merging patches with multiple commits, try to make each patch meaningful.For example, fixes to patches should be squashed into the original patch. Security issues and other serious issues should be avoided in intermediate patches – even if they are fixed in later patches.
+
+- Avoid plain `git merge`, and use rebasing instead, to avoid merge commits. This keeps the history much more readable for others to understand, review bisect and rollback.
+- When merging patches with multiple commits, try to make each patch meaningful.For example, fixes to patches should be squashed into the original patch. Security issues and other serious issues should be avoided in intermediate patches – even if they are fixed in later patches.
 
 That's all folks! And Happy contributing!!

README.md

@@ -6,31 +6,37 @@
 
 > What [CI/CD](https://en.wikipedia.org/wiki/CI/CD) should've been.
 
-Most CI/CD tools are too opinionated and do too much. Bob follows the UNIX philosophy of doing one thing and doing it well, and the Emacs/LISP like philosophy of small core with external extensibility, and strives for [simpler, decomposed and hence more composable and unbundled design](https://www.youtube.com/watch?v=MCZ3YgeEUPg). For more information, see [Why Bob](https://bob-cd.github.io/pages/why-bob.html)
+Most CI/CD tools are too opinionated and do too much. Bob follows the UNIX philosophy of doing one thing and doing it well, and the Emacs/LISP like philosophy of small core with external extensibility, and strives for [simpler, decomposed and hence more composable and unbundled design](https://www.youtube.com/watch?v=MCZ3YgeEUPg). For more information, see [Why Bob](https://bob-cd.github.io/rationale/)
 
 ## Getting Started
-To build and run your pipelines, check out the [Getting Started](https://bob-cd.github.io/pages/getting-started.html) guide.
+
+To build and run your pipelines, check out the [Getting Started](https://bob-cd.github.io/getting-started/) guide.
 
 ## Overview
+
 Bob's API (accessible entirely through HTTP) enables a core set of CI/CD features. The following are the only concepts that Bob is opinionated about:
+
 - Step: Direct commands (like a shell command, `pytest`, etc)
 - Pipeline: Ordered series of steps
 - Environment: Key-Value pair associated with either Steps and/or Pipelines
 - Resource: Things (like source code or artifacts) consumed by Pipelines
 - Artifact: Something produced by a Pipeline
 
 The following services form the core cluster:
+
 - [API server](/apiserver)
 - [Runner](/runner)
 
-All of these services live, breathe, and deploy from their own section of this mono-repo. Post-deployment, they are coordinated via a central persistent queue. Read more about Bob's [Architecture](https://bob-cd.github.io/pages/architecture.html).
+All of these services live, breathe, and deploy from their own section of this mono-repo. Post-deployment, they are coordinated via a central persistent queue. Read more about Bob's [Architecture](https://bob-cd.github.io/architechture/).
 
 ## Join the conversation
+
 Please start a [discussion](https://github.com/bob-cd/bob/discussions) on literally any topic and we are happy to help and learn from each other!
 
 For a more Clojure specific discussion there we also have a Clojurians Slack [channel](https://clojurians.slack.com/messages/CPBAYJJF6).
 
 Happy Building!
 
 ## License
+
 Bob is [Free](https://www.gnu.org/philosophy/free-sw.en.html) and Open Source and always will be. Licensed fully under [MIT](https://opensource.org/licenses/MIT)

apiserver/README.md

@@ -3,16 +3,18 @@
 This is the coherent gateway for the Bob cluster having the REST API, schema checks, health checks for all the services and useful overviews like system status and metrics.
 
 ## How does this work
+
 - This is implemented in Clojure/JVM
 - Implements a [spec-first](https://www.atlassian.com/blog/technology/spec-first-api-development) REST API with this OpenAPI 3.0+ [schema](/apiserver/src/main/resources/bob/api.yaml)
 - Uses [RabbitMQ](https://www.rabbitmq.com/) to send the requests from the API and receive events from the runner via RabbitMQs streams interface
 - Uses [XTDB](https://xtdb.com) backed by [PostgreSQL](https://www.postgresql.org/) for reading the cluster state
 
 ## Configuration
+
 [Aero](https://github.com/juxt/aero) is used and therefore several variables can be set by specifying them as environment variables. Possible variables are:
 
 | Environment variables         | defaults                                         |
-|-------------------------------|--------------------------------------------------|
+| ----------------------------- | ------------------------------------------------ |
 | BOB_STORAGE_URL               | jdbc:postgresql://localhost:5432/bob             |
 | BOB_STORAGE_USER              | bob                                              |
 | BOB_STORAGE_PASSWORD          | bob                                              |
@@ -32,6 +34,7 @@ This is the coherent gateway for the Bob cluster having the REST API, schema che
 ## Building and Running
 
 ### Requirements, min versions, latest recommended.
+
 - JDK 19+
 - RabbitMQ 3.13+ with the [management-plugin](https://www.rabbitmq.com/docs/management)
 - PostgreSQL 11+
@@ -40,18 +43,22 @@ This is the coherent gateway for the Bob cluster having the REST API, schema che
 - (Optional) A bob artifact store like [artifact-local](https://github.com/bob-cd/artifact-local)
 
 ### Using Docker to easily boot up a local cluster
+
 - Install Docker 18+ and start it up
 - Run `docker run -it --name bob-queue -p 5672:5672 -p 15672:15672 -p 5552:5552  -e RABBITMQ_SERVER_ADDITIONAL_ERL_ARGS='-rabbitmq_stream advertised_host localhost' --entrypoint sh rabbitmq:management-alpine -c 'rabbitmq-plugins enable --offline rabbitmq_stream && rabbitmq-server'` to run the latest management enabled RabbitMQ instance on port `5672`, the streams interface on port `5552` and the admin control on port `15672`. The default credentials are `guest:guest`.
 - Run `docker exec bob-queue rabbitmq-plugins enable rabbitmq_stream` to enable the stream plugin on the RabbitMQ instance.
 - Run `docker run --rm -it --name bob-storage -p 5432:5432 -e POSTGRES_DB=bob -e POSTGRES_USER=bob -e POSTGRES_PASSWORD=bob postgres:alpine` to run the latest PostgreSQL instance on port `5432`.
 
 ### Ways of connecting APIServer to the cluster
+
 - To build an uberjar run `bb compile` to obtain an `apiserver.jar`. Running `java --enable-preview -jar apiserver.jar` should connect to it.
 - To run directly without building a JAR, run `clojure -J--enable-preview -M -m apiserver.main` from this dir.
 
 ## Setting up the dev environment with the REPL
+
 - This uses [Integrant](https://github.com/weavejester/integrant) to manage state across the app.
 - When loaded into the editor/REPL, find the `reset` fn in this [namespace](/apiserver/src/apiserver/system.clj). Eval this when there is change to reload the state cleanly.
 
 ### Running integration tests
+
 Run `bb test` from this dir. (needs docker)

doc/adr/0003-introduce-queue.md

@@ -9,6 +9,7 @@ Accepted
 ## Context
 
 The current design is based around a single Bob node written in Clojure responsible for:
+
 - Exposing the REST API
 - Implementing the step execution logic via a local Docker daemon
 - Implementing the registration, creation and update of all the resources
@@ -17,26 +18,28 @@ The current design is based around a single Bob node written in Clojure responsi
 This node is expected to be replicated based on the scaling needs and they all would be simply load balanced behind a simple Application Load Balancer like NGINX.
 
 This brings forth the following issues:
+
 - There is no back-pressure support: When the nodes are overwhelmed, there is no way to queue up builds and results in dropping of jobs and errors
 - There is a shared state of where exactly the pipeline is really running and requests like stopping, pausing which need to be exactly delivered to the concerned node. There is no clean way of doing this
 - The node being implemented in Clojure/JVM and using docker to implement the steps has a opinionated view:
-    - Platforms which are either unsupported/resource constrained by the JVM cannot be addressed in a simple manner
-    - Builds with special privileged needs aren't simple to implement
+  - Platforms which are either unsupported/resource constrained by the JVM cannot be addressed in a simple manner
+  - Builds with special privileged needs aren't simple to implement
 - There is no central place for errors and no ability to program/orchestrate on errors. Use case: CD for machine learning
 - The scale bottle neck is the runner but the scale unit is the whole of Bob which is quite suboptimal
 - It's not simple to implement a declarative style of CI/CD without queueing and back-pressure
 
 ## Decision
 
 Based on the above facts the following is decided:
+
 - Break the core up into 3 services:
-    - API Server, implementing the spec-first API
-    - Entities, implementing the creation, registration of entities like Pipeline, Resource Provider and Artifact Store
-    - Runner, implementing the step execution logic based on Docker, streaming of logs to DB and pushing out the errors to the queue
+  - API Server, implementing the spec-first API
+  - Entities, implementing the creation, registration of entities like Pipeline, Resource Provider and Artifact Store
+  - Runner, implementing the step execution logic based on Docker, streaming of logs to DB and pushing out the errors to the queue
 - Use [RabbitMQ](https://www.rabbitmq.com/) as the central queue and rendezvous point for all the services for the following reasons:
-    - It's quite ubiquitous and well battle tested
-    - The protocol and client ecosystem is quite diverse and mature
-    - It's quite resilient and independently scalable
+  - It's quite ubiquitous and well battle tested
+  - The protocol and client ecosystem is quite diverse and mature
+  - It's quite resilient and independently scalable
 - Use the fanout capabilities of the queue to broadcast the stop, pause requests to all connected runners
 
 ## Consequences

doc/adr/0004-introduce-temporal-db.md

@@ -12,6 +12,7 @@ Currently we are using a traditional RDBMS, PostgreSQL as the storage of all the
 The DB is the one and only state of the whole CI/CD cluster, storing all of the pipeline, resource, artifact definitions, runs, logs etc. For all of these, tracking historical changes is of utmost importance.
 
 Using a traditional CRUD workflow with PostgeSQL raises the following issues:
+
 - Analytics are really hard as the Storage and Querying is coupled and a heavy query slows the whole cluster down
 - Central locking is a severe impediment to scale
 - When a change occurs in the pipeline, resource provider or artifact store definition its quite difficult to track these changes across time for audit and rollback needs
@@ -22,11 +23,12 @@ Using a traditional CRUD workflow with PostgeSQL raises the following issues:
 ## Decision
 
 Based on the above facts the following is decided:
+
 - Use [XTDB](https://xtdb.com) as the temporal, document store for the following reasons:
-    - Though being newer compared to [Datomic](https://www.datomic.com/) its free and open source and ready for production use
-    - Has a quite unbundled design and uses a variety of storage backends and is transactor free
-    - Is [bi-temporal](https://xtdb.com/articles/bitemporality.html) and thereby offering more systematic analytical queries across time
-    - Has an HTTP interface for non JVM clients
+  - Though being newer compared to [Datomic](https://www.datomic.com/) its free and open source and ready for production use
+  - Has a quite unbundled design and uses a variety of storage backends and is transactor free
+  - Is [bi-temporal](https://xtdb.com/articles/bitemporality.html) and thereby offering more systematic analytical queries across time
+  - Has an HTTP interface for non JVM clients
 - Use it with JDBC/PostgreSQL backend which is quite readily available and managed in all popular cloud providers
 - Remove the CRUD way of doing things, expose the DB too via API for more powerful, direct analytical querying
 

doc/adr/0005-introduce-unprivileged-runtime.md

@@ -13,6 +13,7 @@ Given its maturity, ubiquitous deployment and tooling around it, it gave us grea
 Bob is what it is mainly due to the enablement Docker had.
 
 However, it raises the following issues:
+
 - Docker mainly runs as a daemon and moreover **needs root access** for the daemon function
 - Bob is generally intended as a [Cloud Native](https://en.wikipedia.org/wiki/Cloud_native_computing) tool which means all components should be containerized.
   - Given that docker needs root permissions to run, the runner needs to be privileged to function, causing a security risk to the cluster
@@ -22,6 +23,7 @@ However, it raises the following issues:
 ## Decision
 
 Based on the above facts the following is decided:
+
 - Use [Podman](https://podman.io/) as the container runtime and orchestration engine for the following reasons:
   - It is rootless and daemonless
   - Developed by [RedHat](https://www.redhat.com/) and the [OCI](https://opencontainers.org/) community

doc/dev.md

@@ -26,6 +26,7 @@ When developing the Runner, its a bit different as it needs Podman to be availab
 `CONTAINER_ENGINE_URL` can be set to change this.
 
 As above, before starting up the Runner with `clojure -J--enable-preview -M -m runner.main`, make sure podman is running with:
+
 ```shell
 docker run \
 --rm \