From 8f4e8209adbbdf54f0771ee354c49722b14c07f5 Mon Sep 17 00:00:00 2001
From: Chris Kipp <ckipp@pm.me>
Date: Fri, 8 Jul 2022 20:13:43 +0200
Subject: [PATCH] docs: getting real... adding a readme

---
 README.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ebbe51b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,78 @@
+# Mill GitHub Dependency Graph
+
+A [Mill](https://com-lihaoyi.github.io/mill/mill/Intro_to_Mill.html) plugin to
+submit your dependency graph to GitHub via their [Dependency Submission
+API](https://github.blog/2022-06-17-creating-comprehensive-dependency-graph-build-time-detection/).
+
+## Requirements
+
+- Right now this plugin requires **at least Mill 0.10.3**.
+- Make sure in your repo settings the Dependency Graph feature is enabled as
+    well as Dependabot Alerts if you'd like them. (Settings -> Code security and
+    analysis) 
+
+## Quick Start
+
+In the future there will be a GitHub Action for this, but for now the quickest
+way to get started with this at the moment is to create a workflow in your
+project with the following:
+
+```yml
+name: github-dependency-graph
+
+on:
+  push:
+    branches:
+      - main
+
+env:
+  GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+
+jobs:
+  style-check:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+    - uses: coursier/cache-action@v6
+    - uses: actions/setup-java@v3
+      with:
+        distribution: 'temurin'
+        java-version: '17'
+
+    - name: Submit dependency graph
+      run: 
+        ./mill --import ivy:io.chris-kipp::mill-github-dependency-graph_mill0.10:0.0.9 io.kipp.mill.github.dependency.graph.Graph/submit
+```
+
+You can also just run the following command from the root of your workspace
+which will create the file for you:
+
+```sh
+curl -o .github/workflows/github-dependency-graph.yml --create-dirs https://raw.githubusercontent.com/ckipp01/mill-github-dependency-graph/main/.github/workflows/github-dependency-graph.yml
+```
+The plugin is an [external
+module](https://com-lihaoyi.github.io/mill/mill/Modules.html#_external_modules)
+so you don't need to include it in your build. After you submit your graph
+you'll be able to [view your
+dependencies](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/exploring-the-dependencies-of-a-repository#viewing-the-dependency-graph).
+
+## How's this work?
+
+The general idea is that the plugin works in a few steps:
+
+1. Gather all the modules in your build
+2. Gather all direct and transitive dependencies of those modules
+3. Create a tree-like structure of these dependencies. We piggy back off
+   coursier for this and use its `DependencyTree` functionality.
+4. We map this structure to that of a [`DependencySnapshot`](https://github.com/ckipp01/mill-github-dependency-graph/blob/main/domain/src/io/kipp/github/dependency/graph/domain/DependencySnapshot.scala), which is what GitHub understands
+5. We post this data to GitHub.
+
+You can use another available task to see what the
+[`Manifest`s](https://github.com/ckipp01/mill-github-dependency-graph/blob/main/domain/src/io/kipp/github/dependency/graph/domain/Manifest.scala)
+look like locally for your project, which are the main part of the
+`DependencySnapshot`.
+
+
+```sh
+./mill --import ivy:io.chris-kipp::mill-github-dependency-graph_mill0.10:0.0.9 io.kipp.mill.github.dependency.graph.Graph/generate
+```