From 3979be4ccee7702a8bbe10bd6dc512eae6e21949 Mon Sep 17 00:00:00 2001
From: Egor Tensin <Egor.Tensin@gmail.com>
Date: Wed, 12 Jul 2023 22:12:56 +0200
Subject: add DEVELOPMENT.md

---
 .github/workflows/ci.yml |  3 +--
 DEVELOPMENT.md           | 42 ++++++++++++++++++++++++++++++++++++++++++
 README.md                | 30 +-----------------------------
 3 files changed, 44 insertions(+), 31 deletions(-)
 create mode 100644 DEVELOPMENT.md

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 96d8d0b..a791e75 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -3,8 +3,7 @@ name: CI
 on:
   push:
     paths-ignore:
-      - 'docs/**'
-      - 'README.md'
+      - '*.md'
   pull_request:
   workflow_dispatch:
 
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
new file mode 100644
index 0000000..7006dc4
--- /dev/null
+++ b/DEVELOPMENT.md
@@ -0,0 +1,42 @@
+Workspace setup
+---------------
+
+* Create a virtual Python environment: `make venv`
+* Use the virtual environment: `. .venv/bin/activate`
+    * Deactivate the environment when you're done: `deactivate`
+* Make sure unit tests work: `make test/unit`
+
+Development
+-----------
+
+* Run unit tests: `make test/unit`
+* There're three integration tests: `local`, `docker` and `example`.
+Run them using
+
+      make test/local
+      sudo make test/docker
+      make test/example
+
+    * The `example` test uses the forges' APIs and might easily hit rate
+limits.
+Set environment variables described in [examples/cgitize.toml] to use "access
+tokens" and get much higher rate limits.
+
+[examples/cgitize.toml]: examples/cgitize.toml
+
+Upgrading dependencies
+----------------------
+
+* Upgrade virtual environment packages: `make venv/upgrade`
+* Upgrade base Docker images.
+    * Find the current base images using `git grep -P 'FROM \w+:'`
+* Upgrade the [cmark-gfm] version used in the [cgitize-frontend Docker image].
+
+[cmark-gfm]: https://github.com/github/cmark-gfm
+[cgitize-frontend Docker image]: docker/frontend/Dockerfile
+
+Releases
+--------
+
+* Make a git tag for a new minor version using `make tag`.
+You can then review it and push using `git push --tags`.
diff --git a/README.md b/README.md
index 1450f54..da56ef5 100644
--- a/README.md
+++ b/README.md
@@ -51,35 +51,7 @@ Update the URL of an existing repository mirror:
 Development
 -----------
 
-### Virtual environment
-
-Create a virtual environment:
-
-    make venv
-
-Load a REPL:
-
-    make repl
-
-Upgrade virtual environment packages (this will also update requirements.txt):
-
-    make venv/upgrade
-
-### Releases
-
-Make a git tag (requires a virtual environment):
-
-    make tag
-
-You can then review that the tag is fine and push w/ `git push --tags`.
-
-### Linting
-
-Requires [Pylint].
-
-    pylint cgitize
-
-[Pylint]: https://www.pylint.org/
+See [DEVELOPMENT.md](DEVELOPMENT.md).
 
 License
 -------
-- 
cgit v1.2.3