housekeeping

1 files changed, 51 insertions, 0 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 000000000..fa96d3449
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,51 @@
+# Contributing to AspectJ
+
+AspectJ is a maven project, as such it should import cleanly into your IDE. The project uses github for issue tracking ( https://github.com/eclipse/org.aspectj/issues ).
+
+## Working on the codebase
+
+### Importing the project
+
+#### Eclipse
+
+Simply run the maven project importer and point it at the root of the cloned AspectJ repository. This will import all of the AspectJ
+modules.
+
+Each module comes with its own testsuites however there is a module called `run-all-junit-tests` - within there is a file `RunTheseBeforeYouCommitTests` which you can launch as a JUnit test (rightclick -> RunAs -> Junit Test).
+This will run a few thousand tests to verify your IDE import.
+
+Some tests are conditional based on the JDK you are using in your IDE since they are exercising features only available in recent Java.
+In order to execute all possible tests ensure you are running the tests with the latest available Java JDK release.
+A JRE will likely not suffice because tools like javadoc will be invoked from the tests.
+
+#### IntelliJ
+
+TODO
+
+
+### Developing tests
+
+If developing system tests based on the sources for complete Java applications, follow the pattern in the `tests` module.
+For each version of AspectJ there is a `bugsNNN` folder with subfolders for each issue.
+Then there is a pair consisting of a test specification in a `ajcNNN.xml` file in the `src/test/resources` folder and a `AjcNNNTests.java` source file in the `src/main/java` folder.
+Simply follow the pattern for previous versions to add a new suite for a new version of AspectJ.
+Alongside the `AjcNNNTests` file you might add other test suites for particular new language features of Java.
+All these suites are then pulled together in a `AllTestsAspectJNNN.java` suite.
+In turn the suites are pulled together in a `AllTestsNN` suite for the major version of AspectJ, and so on.
+
+Creating a test is then this basic process:
+- create a new folder based on the issue number in the correct `bugsNNN` folder.
+Add the relevant material into that folder (.java sources, any resources, xml files, etc).
+- Create a definition of the test steps ('build these files', 'package this jar from these classes') in the correct `ajcNNN.xml` file in the `src/main/resources` area.
+- Created a test in the correct `AjcNNNTests.java` file that references the specification written in the XML.
+
+### Compiler issues
+
+AspectJ is based on a modified Eclipse JDT that is using a modified grammar, extended to support AspectJ constructs.
+This modified compiler exists in a separate repository: https://github.com/eclipse/aspectj.eclipse.jdt.core
+
+Some issues involving compiler problems, for example if Java code isn't working because a variable was named after an AspectJ keyword - these issues must be worked on in that other project, even though the tests for that will likely live in this project.
+
+## Contributions
+
+Please contribute via Pull Request against the GitHub repository.
\ No newline at end of file