1 files changed, 84 insertions, 4 deletions
diff --git a/gems/gitlab-housekeeper/README.md b/gems/gitlab-housekeeper/README.md
index f707b99c6f0..25d68e67bd8 100644
--- a/gems/gitlab-housekeeper/README.md
+++ b/gems/gitlab-housekeeper/README.md
@@ -1,6 +1,86 @@
 # Gitlab::Housekeeper
 
-Housekeeping following https://gitlab.com/gitlab-org/gitlab/-/merge_requests/134487
+This is a gem which can be run locally or in CI to do static and dynamic
+analysis of the GitLab codebase and, using a list of predefined "keeps", it will
+automatically create merge requests for things that developers would have
+otherwise needed to remember to do themselves.
+
+It is analogous to a mix of `rubocop -a` and GitLab Dependency Bot.
+
+The word "keep" is used to describe a specific rule to apply to the code to
+match a required change and actually edit the code. The word "keep" was chosen
+as it sounds like "cop" and is very similar to implementing a rubocop rule as
+well as code to autocorrect the rule.
+
+You can see the existing keeps in
+https://gitlab.com/gitlab-org/gitlab/-/tree/master/keeps .
+
+## How the code is organized
+
+The code is organized in a very similar way to RuboCop in that we have an
+overall gem called `gitlab-housekeeper` that contains the generic logic of
+looping over all `keeps` (analogous to Cops) which are rules for how to detect
+changes that can be made to the code and then actually how to correct them.
+
+Then users of this gem are expected to add a `keeps` directory in their project
+with all the keeps specific to their project. This gem may at some point
+include keeps that are generic enough to be used by other projects.
+
+## How to implement a keep
+
+The only thing you need to implement is an `each_change` method. The method
+should yield changes in the form of a `::Gitlab::Housekeeper::Change` object,
+where each change object represents a merge request that will be created.
+The object describes the files that should be commited and other metadata
+should be added to the merge request. Before yielding the `Change` the keep
+should also edit the files locally.
+
+Here is an example of a very simple keep that creates 3 new files called
+`new_file1.txt`, `new_file2.txt` and `new_file3.txt`:
+
+```ruby
+# keeps/pretty_useless_keep.rb
+
+module Keeps
+  class PrettyUselessKeep < ::Gitlab::Housekeeper::Keep
+    def each_change
+      (1..3).each do |i|
+        file_name = "new_file#{i}.txt"
+
+        `touch #{file_name}`
+
+        identifiers = [self.class.name.demodulize, "new_file#{i}"]
+
+        title = "Make new file #{file_name}"
+
+        description = <<~MARKDOWN
+        ## New files
+
+        This MR makes a new file #{file_name}
+        MARKDOWN
+
+        labels = %w(type::feature)
+
+        changed_files = [file_name]
+
+        yield(::Gitlab::Housekeeper::Change.new(
+          identifiers, title, description, changed_files, labels
+        ))
+      end
+    end
+  end
+end
+```
+
+You can dry-run this locally with the following command:
+
+```
+bundle exec gitlab-housekeeper -r keeps/pretty_useless_keep.rb -k Keeps::PrettyUselessKeep -d -m 3
+```
+
+The `-d` just prints the contents of the merge request. Removing this will
+actually create merge requests and requires setting a few environment
+variables described below.
 
 ## Running
 
@@ -14,7 +94,7 @@ a mistake. The alternative of using your own API token with it's permissions to
 1. Create a project access token for that project
 1. Set `housekeeper` remote to the fork you created
    ```
-   git remote add housekeeper git@gitlab.com:DylanGriffith/gitlab.git
+   git remote add housekeeper <FORK_GIT_URL>
    ```
 1. Open a Postgres.ai tunnel on localhost port 6305
 1. Set the Postgres AI env vars matching the tunnel details for your tunnel
@@ -24,8 +104,8 @@ a mistake. The alternative of using your own API token with it's permissions to
    ```
 1. Set the GitLab client details. Will be used to create MR from housekeeper remote:
    ```
-   export HOUSEKEEPER_FORK_PROJECT_ID=52263761 # Same project as housekeeper remote
-   export HOUSEKEEPER_TARGET_PROJECT_ID=52263761 # Can be 278964 (gitlab-org/gitlab) when ready to create real MRs
+   export HOUSEKEEPER_FORK_PROJECT_ID=<FORK_PROJECT_ID> # Same project as housekeeper remote
+   export HOUSEKEEPER_TARGET_PROJECT_ID=<TARGET_PROJECT_ID> # Can be 278964 (gitlab-org/gitlab) when ready to create real MRs
     export HOUSEKEEPER_GITLAB_API_TOKEN=the-api-token
    ```
 1. Run it: