From b312ee95cb643c24ed9687d545325b4cb83be8cc Mon Sep 17 00:00:00 2001
From: Dave Brophy <dave@brophy.uk>
Date: Sun, 29 May 2022 18:51:28 -0300
Subject: [PATCH] Tweaked contributing section and moved to separate readme

---
 README.md       | 85 +++----------------------------------------------
 README.md.tpl   | 85 +++----------------------------------------------
 contributing.md | 78 +++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 86 insertions(+), 162 deletions(-)
 create mode 100644 contributing.md

diff --git a/README.md b/README.md
index b03e5a2..bb8c7f4 100644
--- a/README.md
+++ b/README.md
@@ -697,87 +697,10 @@ This package is well tested and used in many projects. The API should be conside
 Feel free to create an [issue](https://github.com/dave/dst/issues) or chat in the 
 [#dst](https://gophers.slack.com/messages/CCVL24MTQ) Gophers Slack channel.
 
+## Contributing
 
-## Building/Developing/Contributing
+For further developing or contributing to `dst`, check out [these notes](https://github.com/dave/dst/blob/master/contributing.md).
 
-The `dst` package relies heavily on code generation. So heavily, in fact, that *this* `README.md` is
-itself generated by a preprocessor! Here are a few tips/tricks to get started developing `dst`.
+## Special thanks
 
-### Adding Features, Fixing Bugs
-
-Generally speaking, code handling node annotation is generated from the files in the `gendst` directory.
-In order to add/change decorations, edit the `gendst/data.go` file. Once you have made your edits, you can
-regenerate the library's source code based on those changes by
-
-1. `go run github.com/dave/dst/gendst`: This command will build and run a program generated from the
-source code in the `gendst` folder that regenerates all the dst source fiels to reflect the changes
-that you just made in the `gendst/data.go` file.
-
-Whenever you make a change to the `gendst/data.go` file, you must perform the aforementioned step.
-
-If you add a Node to the `gendst/data.go` file, you will need to make corresponding additions to non-generated
-files as well. Those files include, but are not limited to,:
-
-- `dst.go`
-- `walk.go`
-- `dstutil/rewrite.go`
-
-Depending on the changes that you have made to the description of the decorated Nodes, you may have to change some, none,
-or all of those files listed above (or even others that are not listed!).
-
-### Adding/Running Tests
-
-Test files are also generated. Any changes to the decorations of Nodes (or the addition of new Nodes) should be accompanied
-by tests. The easiest way to generate tests is to make additions to the `gendst/positions.go` file.
-
-The format of the file is ...
-
-```
-// <NodeTypeName>
-// <Example of NodeType used (in real go), with a comment in every decoration point
-// whose contents are the name of the decoration point.
-```
-
-For instance,
-
-```
-// Field
-type A struct {
-	/*Start*/ A int /*Type*/ `a:"a"` /*End*/
-}
-```
-
-will generate a test that guarantees that all the decoration points for an `Field` node are handled correctly.
-It is important to see that, although the `Field` node is *wrapped* in a `TypeSpec`, only the `Field` decoration
-points are labeled here. That is because the `// Field` that precedes the code indicates that this test is specifically
-for a `Field` node.
-
-As with the `gendst/data.go` file, if you make changes to the `gendst/positions.go` file, you will need to run
-
-1. `go run github.com/dave/dst/gendst`
-
-to bring all the sources files in the project into sync.
-
-Once you have generated new tests, running the test suite is straightforward:
-
-```
-go test ./...
-```
-
-### Updating This README.md
-
-Make all content changes in the `README.md.tpl` file. Then, regenerate `README.md` with
-
-```
-becca -package .
-```
-
-You can install `becca` using the `go` tools:
-
-```
-go install github.com/dave/rebecca/cmd/becca@latest
-```
-
-You can find out more about `becca` at the project's [GitHub](https://github.com/dave/rebecca).
-
-*N.B.:* The above commands assume that you are running go version 1.18 or greater.
\ No newline at end of file
+Thanks very much to @hawkinsw for taking on the task of adding generics compatibility to `dst`.
\ No newline at end of file
diff --git a/README.md.tpl b/README.md.tpl
index 29095f1..4edeaee 100644
--- a/README.md.tpl
+++ b/README.md.tpl
@@ -230,87 +230,10 @@ This package is well tested and used in many projects. The API should be conside
 Feel free to create an [issue](https://github.com/dave/dst/issues) or chat in the 
 [#dst](https://gophers.slack.com/messages/CCVL24MTQ) Gophers Slack channel.
 
+## Contributing
 
-## Building/Developing/Contributing
+For further developing or contributing to `dst`, check out [these notes](https://github.com/dave/dst/blob/master/contributing.md).
 
-The `dst` package relies heavily on code generation. So heavily, in fact, that *this* `README.md` is
-itself generated by a preprocessor! Here are a few tips/tricks to get started developing `dst`.
+## Special thanks
 
-### Adding Features, Fixing Bugs
-
-Generally speaking, code handling node annotation is generated from the files in the `gendst` directory.
-In order to add/change decorations, edit the `gendst/data.go` file. Once you have made your edits, you can
-regenerate the library's source code based on those changes by
-
-1. `go run github.com/dave/dst/gendst`: This command will build and run a program generated from the
-source code in the `gendst` folder that regenerates all the dst source fiels to reflect the changes
-that you just made in the `gendst/data.go` file.
-
-Whenever you make a change to the `gendst/data.go` file, you must perform the aforementioned step.
-
-If you add a Node to the `gendst/data.go` file, you will need to make corresponding additions to non-generated
-files as well. Those files include, but are not limited to,:
-
-- `dst.go`
-- `walk.go`
-- `dstutil/rewrite.go`
-
-Depending on the changes that you have made to the description of the decorated Nodes, you may have to change some, none,
-or all of those files listed above (or even others that are not listed!).
-
-### Adding/Running Tests
-
-Test files are also generated. Any changes to the decorations of Nodes (or the addition of new Nodes) should be accompanied
-by tests. The easiest way to generate tests is to make additions to the `gendst/positions.go` file.
-
-The format of the file is ...
-
-```
-// <NodeTypeName>
-// <Example of NodeType used (in real go), with a comment in every decoration point
-// whose contents are the name of the decoration point.
-```
-
-For instance,
-
-```
-// Field
-type A struct {
-	/*Start*/ A int /*Type*/ `a:"a"` /*End*/
-}
-```
-
-will generate a test that guarantees that all the decoration points for an `Field` node are handled correctly.
-It is important to see that, although the `Field` node is *wrapped* in a `TypeSpec`, only the `Field` decoration
-points are labeled here. That is because the `// Field` that precedes the code indicates that this test is specifically
-for a `Field` node.
-
-As with the `gendst/data.go` file, if you make changes to the `gendst/positions.go` file, you will need to run
-
-1. `go run github.com/dave/dst/gendst`
-
-to bring all the sources files in the project into sync.
-
-Once you have generated new tests, running the test suite is straightforward:
-
-```
-go test ./...
-```
-
-### Updating This README.md
-
-Make all content changes in the `README.md.tpl` file. Then, regenerate `README.md` with
-
-```
-becca -package .
-```
-
-You can install `becca` using the `go` tools:
-
-```
-go install github.com/dave/rebecca/cmd/becca@latest
-```
-
-You can find out more about `becca` at the project's [GitHub](https://github.com/dave/rebecca).
-
-*N.B.:* The above commands assume that you are running go version 1.18 or greater.
\ No newline at end of file
+Thanks very much to @hawkinsw for taking on the task of adding generics compatibility to `dst`.
\ No newline at end of file
diff --git a/contributing.md b/contributing.md
new file mode 100644
index 0000000..dc02406
--- /dev/null
+++ b/contributing.md
@@ -0,0 +1,78 @@
+# Building / Developing / Contributing
+
+The `dst` package relies heavily on code generation. So heavily, in fact, that `README.md` is
+itself generated by a preprocessor! Here are a few tips/tricks to get started developing `dst`.
+
+## Adding Features, Fixing Bugs
+
+Generally speaking, code handling node annotation is generated from the files in the `gendst` directory.
+In order to add/change decorations, edit the `gendst/data.go` file. Once you have made your edits, you can
+regenerate the library's source code based on those changes by
+
+1. `go run github.com/dave/dst/gendst`: This command will build and run a program generated from the
+   source code in the `gendst` folder that regenerates all the dst source fiels to reflect the changes
+   that you just made in the `gendst/data.go` file.
+
+Whenever you make a change to the `gendst/data.go` file, you must perform the aforementioned step.
+
+If you add a Node to the `gendst/data.go` file, you will need to make corresponding additions to non-generated
+files as well. Those files include, but are not limited to,:
+
+- `dst.go`
+- `walk.go`
+- `dstutil/rewrite.go`
+
+Depending on the changes that you have made to the description of the decorated Nodes, you may have to change some, none,
+or all of those files listed above (or even others that are not listed!).
+
+## Adding/Running Tests
+
+Any changes to the decorations of Nodes (or the addition of new Nodes) should be accompanied
+by an entry in `gendst/positions.go`.
+
+The format of the file is ...
+
+```
+// <NodeTypeName>
+// <Example of NodeType used (in real go), with a comment in every decoration point
+// whose contents are the name of the decoration point.
+```
+
+For instance,
+
+```
+// Field
+type A struct {
+	/*Start*/ A int /*Type*/ `a:"a"` /*End*/
+}
+```
+
+will generate a test that guarantees that all the decoration points for an `Field` node are handled correctly.
+It is important to see that, although the `Field` node is *wrapped* in a `TypeSpec`, only the `Field` decoration
+points are labeled here. That is because the `// Field` that precedes the code indicates that this test is specifically
+for a `Field` node.
+
+As with the `gendst/data.go` file, if you make changes to the `gendst/positions.go` file, you will need to run 
+`gendst` to bring all the sources files in the project into sync.
+
+Once you have generated new tests, running the test suite is straightforward:
+
+```
+go test ./...
+```
+
+## Updating This README.md
+
+Make all content changes in the `README.md.tpl` file. Then, regenerate `README.md` with
+
+```
+becca -package .
+```
+
+You can install `becca` using the `go` tools:
+
+```
+go install github.com/dave/rebecca/cmd/becca@latest
+```
+
+You can find out more about `becca` at the project's [GitHub](https://github.com/dave/rebecca).