From ce55fe01b88e011d6773515f92555c9a4c2ba141 Mon Sep 17 00:00:00 2001 From: eltrac Date: Fri, 23 Oct 2026 18:55:56 +0800 Subject: docs: update Contributors' Guide; add storage.md to User Manual --- doc/CONTRIBUTING.md | 15 ++++++++++++--- doc/manual/storage.md | 34 ++++++++++++++++++++++++++++++++++ 2 files changed, 46 insertions(+), 3 deletions(-) create mode 100644 doc/manual/storage.md diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md index 59b42df..38a0272 100644 --- a/doc/CONTRIBUTING.md +++ b/doc/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing to Weepinbell -Contributions are welcome and greatly appreciated, as long as you follow the rules. +Contributions are welcome and greatly appreciated. Get started here! ## First step @@ -14,7 +14,7 @@ Don't create a PR if it hasn't been discussed and approved in an issue yet! If y ### Code style -1. Functions should be small and does one thing only. +1. Functions should be small and does one thing only, with clear or no side effects[^2]. 2. A file should have less than 150 lines of code.[^1] 3. Test-Driven Development is not enforced, but committing tests alongside your code is encouraged. 4. Use utility functions and `->`/`->>` macros to reduce layers of indentation. @@ -34,6 +34,10 @@ Don't create a PR if it hasn't been discussed and approved in an issue yet! If y 1. A feature should be discussed in an issue before it's implemented in a PR. 2. When writing a function, write docstring first. 3. When designing a new component, write namespace's docstring first. +4. After a architecture decision, document the context and final decision in [ADR](./doc/adr/). (Also, read existing ADRs to understand why things are what they are) + +> [!tip] +> Write and communicate in [Simple English](https://simple.wikipedia.org/wiki/Basic_English), so the project can be more inclusive of people who speak English as a second language and people with dyslexia. ### Minimal dependencies @@ -70,7 +74,7 @@ To start REPL: lein repl ``` -To start a dev server (and an REPL): +To start a dev server that automatically reloads namespaces on file changes (and an REPL): ``` lein dev @@ -122,4 +126,9 @@ The following usage of LLMs is strictly forbidden: 2. Generating code that has not been significantly modified by the contributors themselves. (By "significantly", I mean "significantly enough to claim copyright of this piece of code") 3. Spread information generated by an LLM without verifying it yourself. +## Licensing + +By contributing to weepinbell, you agree to license your code under GNU Affero General Public License. + [^1]: It should be more than enough for Clojure. If not, consider refactoring. +[^2]: See *Functional Programming* diff --git a/doc/manual/storage.md b/doc/manual/storage.md new file mode 100644 index 0000000..20f905b --- /dev/null +++ b/doc/manual/storage.md @@ -0,0 +1,34 @@ +# Storage + +Weepinbell currently supports 2 types of storage, both file-based. + +## Configuration + +Options related to data storage: + +```edn + :storage-type :edn ; or :h2 + :data-path "webmention.edn" ; or H2 database name +``` + +By default, weepinbell uses EDN storage and writes data to `data/webmention.edn`. + +## EDN file-based storage + +> [!note] +> If you're not familiar with this format, see [edn](https://github.com/edn-format/edn). In short, it's Clojure's equivalent of JSON, but more extensible. + +When `:storage-type` is set to `:edn`, weepinbell writes to and reads from a `.edn` file, but more accurately, it's in "EDN lines" format, like JSONL. Every line is a valid EDN data. Every line is a webmention entry. Every entry is a map containing the following keys: `:webmention`, `:microformats`, `:extra`. + +It's not recommended to edit data file directly by hand, but if you must, back up before you do. Also, it's considered good practice to set up a cron job to routinely back up data file. + +If you don't have much data, using a single EDN would be enough, though the current implementation is not performant and very slow. + +## H2 database + +H2 is a file-based SQL database in pure Java. Like SQLite, it's lightweight and fast. Unlike SQLite, it does not need a native C library, which is slower but more suitable for Java and Clojure. + +When `:storage-type` is set to `:h2`, weepinbell uses a H2 database. The database is usually two files. The `:data-path` is the name of database, not the filename like EDN file-based storage. Just set `:data-path` to a name you want and weepinbell will create and use relevant files for you. + +This is the recommended storage type. + -- cgit v1.2.3