diff options
| -rw-r--r-- | doc/CONTRIBUTING.md | 15 | ||||
| -rw-r--r-- | doc/manual/storage.md | 34 |
2 files changed, 46 insertions, 3 deletions
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.
+
|