Merge branch 'master' into dogfood-bouncer

.clj-kondo/config.edn

@@ -1,36 +1,44 @@
-{:output  {:pattern "::{{level}} file={{filename}},line={{row}},col={{col}}::{{message}}"}
- :linters {:aliased-namespace-symbol              {:level :warning}
-           :consistent-alias                      {:aliases {clojure.edn           edn
-                                                             clojure.java.io       io
-                                                             clojure.math          math
-                                                             clojure.set           set
-                                                             clojure.walk          walk
-                                                             clojure.zip           zip
-                                                             clojure.core.async    async
-                                                             clojure.data.csv      csv
-                                                             clojure.data.xml      xml
-                                                             clojure.tools.cli     cli
-                                                             clojure.java.shell    sh
-                                                             clojure.pprint        pp
-                                                             clojure.spec.alpha    spec
-                                                             clojure.string        str
-                                                             clojure.core.matrix   mat
-                                                             clojure.tools.logging log
-                                                             clojure.core.reducers r}}
-           :docstring-leading-trailing-whitespace {:level :warning}
-           :keyword-binding                       {:level :warning}
-           :main-without-gen-class                {:level :warning}
-           :missing-docstring                     {:level :warning}
-           :namespace-name-mismatch               {:level :warning}
-           :reduce-without-init                   {:level :warning}
-           :redundant-fn-wrapper                  {:level :warning}
-           :refer                                 {:level   :warning
-                                                   :exclude #{clojure.test cljs.test doo.runner}}
-           :refer-all                             {:exclude #{clojure.test}}
-           :shadowed-var                          {:level :warning}
-           :single-key-in                         {:level :warning}
-           :unresolved-symbol                     {:exclude [(clojure.test/is [match?])
-                                                             clojure.test.check.clojure-test/defspec]}
-           :unsorted-required-namespaces          {:level :warning}
-           :used-underscored-binding              {:level :warning}
-           :unused-value                          {:level :warning}}}
+{:exclude-files ".clj-kondo/imports/.*"
+ :output        {:pattern "::{{level}} file={{filename}},line={{row}},col={{col}}::{{message}}"}
+ :ns-groups     [{:pattern "\\*\\.experimental\\.\\*"
+                  :name    experimental-features}
+                 {:pattern "\\*\\.impl"
+                  :name    implementation-only}]
+ :linters       {:aliased-namespace-symbol              {:level :warning}
+                 :consistent-alias                      {:aliases {clojure.edn           edn
+                                                                   clojure.java.io       io
+                                                                   clojure.math          math
+                                                                   clojure.set           set
+                                                                   clojure.walk          walk
+                                                                   clojure.zip           zip
+                                                                   clojure.core.async    async
+                                                                   clojure.data.csv      csv
+                                                                   clojure.data.xml      xml
+                                                                   clojure.tools.cli     cli
+                                                                   clojure.java.shell    sh
+                                                                   clojure.pprint        pp
+                                                                   clojure.spec.alpha    spec
+                                                                   clojure.string        str
+                                                                   clojure.core.matrix   mat
+                                                                   clojure.tools.logging log
+                                                                   clojure.core.reducers r}}
+                 :discouraged-var                       {clojure.core/read-string {:message "Use `clojure.edn/read-string` instead of `read-string`."}}
+                 :discouraged-namespace                 {experimental-features {:message "These functions are considered experimental and can break or change implementation in future releases."}
+                                                         implementation-only   {:message "These functions are considered internal implementation details and are not part of their respective public api."}}
+                 :docstring-leading-trailing-whitespace {:level :warning}
+                 :keyword-binding                       {:level :warning}
+                 :main-without-gen-class                {:level :warning}
+                 :missing-docstring                     {:level :warning}
+                 :namespace-name-mismatch               {:level :warning}
+                 :reduce-without-init                   {:level :warning}
+                 :redundant-fn-wrapper                  {:level :warning}
+                 :refer                                 {:level   :warning
+                                                         :exclude #{clojure.test cljs.test doo.runner}}
+                 :refer-all                             {:exclude #{clojure.test}}
+                 :shadowed-var                          {:level :warning}
+                 :single-key-in                         {:level :warning}
+                 :unresolved-symbol                     {:exclude [(clojure.test/is [match?])
+                                                                   clojure.test.check.clojure-test/defspec]}
+                 :unsorted-required-namespaces          {:level :warning}
+                 :used-underscored-binding              {:level :warning}
+                 :unused-value                          {:level :warning}}}

.cljstyle

@@ -1,3 +1,6 @@
 {:files {:extensions #{"clj" "cljs" "cljc" "cljx" "edn"}
-         :ignore     #{"target" ".git" ".idea" ".vscode" "node_modules"}}
- :rules {:namespaces {:enabled? false}}}
+         :ignore     #{"target" ".git" ".idea" ".vscode" "node_modules" ".clj-kondo" ".calva" ".lsp"}}
+ :rules {:namespaces  {:enabled? false}
+         :indentation {:indents {#"defspec"              [[:inner 0]]
+                                 #"defstate"             [[:inner 0]]
+                                 #"for-all"              [[:inner 0]]}}}}

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,11 +1,15 @@
 # Proposed Changes
 
+Quickly describe your change and the rationale behind it.
+Please link to any relevant issues or discussions.
+
 - Additions:
 - Updates:
 - Deletions:
 
 ## Pre-merge Checklist
 
-- [ ] Write + run tests
+- [ ] Read and agree to the Contribution Guidelines and Code of Conduct
+- [ ] Write new tests for the changed functionality
 - [ ] Update CHANGELOG and increment version
 - [ ] Update README and relevant documentation

CODEOWNERS

@@ -1,2 +1,6 @@
 # Barring any major exception, all Wall Brew Developers should be maintainers of any file
 * @Wall-Brew-Co/wall-brew-developers
+
+## This file was automatically copied and populated by rebroadcast
+
+## Do not edit this file directly, instead modify the source at <https://github.com/Wall-Brew-Co/rebroadcast/blob/master/sources/community/CODEOWNERS>

CODE_OF_CONDUCT.md

@@ -65,7 +65,7 @@ Representation of a project may be further defined and clarified by project main
 
 ## Enforcement
 
-Any and all instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at contact@wallbrew.com.
+Any and all instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at contact [at] wallbrew [dot] com.
 All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances.
 The project team is obligated to maintain confidentiality with regard to the reporter of an incident.
 Further details of specific enforcement policies may be posted separately.

CONTRIBUTING.md

@@ -7,8 +7,8 @@ Wall Brew strives to make contributions as simple as possible while ensuring our
 
 - [Code of Conduct](#code-of-conduct)
   - [Our Pledge](#our-pledge)
-- [Communicating Changes](#communicating-changes)
-  - [Read the Documentation](#read-the-documentation)
+- [Prior to Contributing](#prior-to-contributing)
+- [Communicating and Contributing Changes](#communicating-and-contributing-changes)
   - [Where To Start](#where-to-start)
 - [Pull Request](#pull-request)
   - [Restricted Files](#restricted-files)
@@ -36,7 +36,13 @@ size, disability, ethnicity, gender identity and expression, level of experience
 
 A full copy of our code of conduct may be found in any Wall Brew repository.
 
-## Communicating Changes
+## Prior to Contributing
+
+Familiarize yourself with the documentation before you submit a Pull Request.
+If you have questions which aren't in the documentation, open a ticket or submit a Pull Request to update the documentation.
+Prior to starting development on an individual fork, we recommend executing the tests locally to confirm the library and your machine are working as expected.
+
+## Communicating and Contributing Changes
 
 For small issues, improvements, and bug fixes, feel free to fork any repository and publish a pull request.
 A Wall Brew maintainer will be automatically assigned for review, and help you understand any remaining steps to merge your changes.
@@ -52,22 +58,17 @@ For issues, reports, and changes that span multiple repositories or would change
 Lastly, to effectively communicate changes to our consumers, please follow the conventions of each repository when writing documentation or adding annotative metadata to functionality.
 This allows us to cleanly and consistently provide our end-users with a high-quality development experience.
 
-### Read the Documentation
-
-Familiarize yourself with the documentation before you submit a Pull Request.
-If you have questions which aren't in the documentation, open a ticket or submit a Pull Request to update the documentation.
-
 ### Where To Start
 
 If you're looking for ways to contribute, but don't know where to start, try adding additional tests.
 Additionally improving documentation or adding examples as you learn a new project can is an easy way to pitch in.
-Finally, check the open [issues and feature requests](https://github.com/nnichols/clj-xml/issues) of the project and ask the maintainers if they are available to be taken on.
+Finally, check the open [issues and feature requests](https://github.com/Wall-Brew-Co/clj-xml/issues) of the project and ask the maintainers if they are available to be taken on.
 
 ## Pull Request
 
 1. Each Wall Brew library follows [SemVer](http://semver.org/ "The Semantic Versioning Scheme"). Please update the version number of any affected projects accordingly.
-2. Update the project's [CHANGELOG.md](https://github.com/nnichols/clj-xml/blob/master/CHANGELOG.md) with the new version, date of changes, and a description of the modifications made
-3. If any changes impact the external interface or use of the library, please update the [README](https://github.com/nnichols/clj-xml/blob/master/README.md) to reflect any relevant differences or with additional documentation.
+2. Update the project's [CHANGELOG.md](https://github.com/Wall-Brew-Co/clj-xml/blob/master/CHANGELOG.md) with the new version, date of changes, and a description of the modifications made with [sealog](https://github.com/Wall-Brew-Co/lein-sealog)
+3. If any changes impact the external interface or use of the library, please update the [README](https://github.com/Wall-Brew-Co/clj-xml/blob/master/README.md) to reflect any relevant differences or with additional documentation.
 4. Be sure to write and update tests that reflect your changes, with good assertion descriptions, and that ensure future contributions will not cause your changes to regress in behavior.
 5. Ensure all automated checks pass against your pull request, and make any updates to fix tests, linter warnings, etc.
 6. A Wall Brew maintainer will be automatically assigned to review your Pull Request. Please consider any changes or enhancements they may suggest. In some cases, at the discretion of individual Wall Brew maintainers, these changes may be pushed onto your branch or added to any pull request.

doc/clojure/patterns/symbolic_keywords.md

@@ -0,0 +1,53 @@
+# Symbolic Keywords
+
+In many clojure libraries, the behavior of complex functions may be controlled by a map.
+For example:
+
+```clojure
+(:require [brewtility.units :as units])
+(units/display :volume 1.5 :liter) ;; => "1.5 l"
+(units/display :volume 1.5 :liter {:suffix :full}) ;; => "1.5 liter"
+```
+
+This allows us to easily extend the definition of a single function to fulfill multiple complex needs; however, option maps come with considerable drawbacks.
+When a map is keyed with keywords, it is easy to introduce subtle, hard-to-detect errors.
+Since most of these functions select default values for keys not present, typos can lead to meaningful differences in behavior.
+For example:
+
+```clojure
+(:require [brewtility.units :as units])
+(units/display :volume 1.5 :liter) ;; => "1.5 l"
+
+;; Note the missing "f" in the key :sufix
+(units/display :volume 1.5 :liter {:sufix :full}) ;; => "1.5 l"
+```
+
+Because keywords aren't picked up by the auto-complete features of most editors, they're vulnerable to all classes of transpositional errors.
+Further, the options themselves are unable to carry metadata and documentation with them, making them little more than magic values.
+
+For this reason, it is helpful for libraries to include symbols which point to the "magic" keywords used in option maps.
+This has several benefits:
+
+- Misspelled or incorrect option keys are compile-time errors, instead of runtime bugs
+- Symbols can carry metadata like documentation, deprecation notices, and point to alternative options
+- Context-aware editors can auto-complete options
+
+Here's an example:
+
+```clojure
+(:require [brewtility.units :as units]
+          [brewtility.units.options :as options])
+
+(units/display options/volume 1.5 options/liter) ;; => "1.5 l"
+(units/display options/volume 1.5 options/liter {options/suffix options/full}) ;; => "1.5 liter"
+```
+
+These keywords are available in the namespaces ending in `.options`.
+These files live as close to the code relying on them as possible;
+for example, the options for all unit conversion operations (e.g. `brewtility.units`, `brewtility.units.time`, `brewtility.units.color`, etc.) are available in `brewtility.units.options`.
+
+Further, the keywords in these namespaces are strictly preferred for library development.
+A single source of truth for the name of a common option, such as `precision`, limits the possibility of incorrectly retrieving the values used by that option.
+
+<!-- This file was automatically copied and populated by rebroadcast -->
+<!-- Do not edit this file directly, instead modify the source at https://github.com/Wall-Brew-Co/rebroadcast/blob/master/sources/community/documentation/clojure/patterns/symbolic_keywords.md -->

doc/developing/001_required_tooling.md

@@ -0,0 +1,109 @@
+# Required Tooling
+
+Development at Wall Brew currently spans two primary programming languages: [clojure](https://clojure.org/) and [javascript.](https://www.javascript.com/)
+To build libraries and applications in those languages we use the two following build tools:
+
+* [Leiningen](https://leiningen.org/)
+* [npm](https://www.npmjs.com/)
+
+We highly recommend using your operating system's preferred package manager to install the following dependencies.
+If you do not have a preferred package manager, we currently recommend [Homebrew.](https://brew.sh/)
+
+For developers working on Windows machines, we strongly recommend the [Windows Subsystem for Linux (WSL).](https://learn.microsoft.com/en-us/windows/wsl/install)
+
+## Clojure Development
+
+### The Java Development Kit
+
+Since clojure is a hosted language within the JVM, a recent JDK is required.
+We recommend and develop against [OpenJDK](https://openjdk.org/) distributions.
+The following Homebrew command will install the most recent distribution:
+
+```sh
+brew install openjdk
+```
+
+You can verify the installation with the following command:
+
+```sh
+$ java --version
+openjdk 21.0.2 2024-01-16
+OpenJDK Runtime Environment Homebrew (build 21.0.2)
+OpenJDK 64-Bit Server VM Homebrew (build 21.0.2, mixed mode, sharing)
+```
+
+If you plan on developing against or regression testing functionality against older JDK versions, we recommend installing [jenv.](https://www.jenv.be/)
+jenv can be installed with the following homebrew command:
+
+```sh
+brew install jenv
+```
+
+You can verify the installation with the following command:
+
+```sh
+$ jenv versions
+* system (set by /some/local/path/.jenv/version)
+```
+
+### Leiningen
+
+Leiningen manages clojure dependencies and tooling, and can be installed with the following homebrew command:
+
+```sh
+brew install leiningen
+```
+
+You can verify the installation with the following command:
+
+```sh
+$ lein -v
+Leiningen 2.11.2 on Java 21.0.2 OpenJDK 64-Bit Server VM
+```
+
+When working in a clojure repository, Leiningen will use a file named `project.clj` in the repository's root to declare library dependencies and tooling plugins.
+Leiningen will automatically download these as-needed while using default commands; however, they can be pre-fetched with the following:
+
+```sh
+lein deps
+```
+
+Individual developer tools should be installed in `.lein/profiles.clj`
+A sample profile is provided below, but can be customized to your needs:
+
+```clj
+{:user {:plugin-repositories [["clojars" {:url "https://clojars.org/repo"}]]
+        :git-dependencies    [["https://github.com/tobyhede/monger.git"]]
+        :plugins             [[com.jakemccrary/lein-test-refresh "0.23.0"]
+                              [lein-cloverage "1.2.4"]
+                              [com.github.liquidz/antq "RELEASE"]
+                              [ns-sort "1.0.3"]]
+        :test-refresh        {:notify-command ["terminal-notifier" "-title" "Tests" "-message"]}}}
+```
+
+Default developer tools will be installed in the `project.clj` file for each Wall Brew repository.
+
+## Clojurescript and Javascript Development
+
+### Node.js
+
+The Node Package Manager manages dependencies and tooling for our javascript projects and our clojurescript testing dependencies.
+It can be installed with the following homebrew command:
+
+```sh
+brew install node
+```
+
+You can verify the installation with the following command:
+
+```sh
+$ npm version
+{
+  npm: '10.2.4',
+  node: '21.6.2',
+  ...
+}
+```
+
+<!-- This file was automatically copied and populated by rebroadcast -->
+<!-- Do not edit this file directly, instead modify the source at https://github.com/Wall-Brew-Co/rebroadcast/blob/master/sources/community/documentation/developing/001_required_tooling.md -->