Documentation on changing the structure of the AST

Author: kddnewton

doc/changing_structure.md

@@ -0,0 +1,16 @@
+# Changing structure
+
+First and foremost, changing the structure of the tree in any way is a major breaking change. It forces the consumers to update their visitors, pattern matches, and method calls. It should not be taking lightly, and can only happen on a major version change. So keep that in mind.
+
+That said, if you do want to change the structure of the tree, there are a few steps that you have to take. They are enumerated below.
+
+1. Change the structure in the required node classes. This could mean adding/removing classes or adding/removing fields. Be sure to also update the `copy` and `===` methods to be sure that they are correct.
+2. Update the parser to correctly create the new structure.
+3. Update any visitor methods that are affected by the change. For example, if adding a new node make sure to create the new visit method alias in the `Visitor` class.
+4. Update the `FieldVisitor` class to be sure that the various serializers, pretty printers, and matchers all get updated accordingly.
+5. Update the `DSL` module to be sure that folks can correctly create nodes with the new structure.
+6. Ensure the formatting of the code hasn't changed. This can mostly be done by running the tests, but if there's a corner case that we don't cover that is now exposed by your change be sure to add test cases.
+7. Update the translation visitors to ensure we're still translating into other ASTs correctly.
+8. Update the YARV compiler visitor to ensure we're still compiling correctly.
+9. Make sure we aren't referencing the previous structure in any documentation or tests.
+10. Be sure to update `CHANGELOG.md` with a description of the change that you made.