windup · sgilda · Mar 17, 2015 · Mar 17, 2015
diff --git a/docs/Core-Development-Guide.asciidoc b/docs/Core-Development-Guide.asciidoc
@@ -11,7 +11,7 @@ or core rule add-ons to the Windup 2.0 project.
 * link:Get-Involved[Get Involved] - We need your feedback!
 * link:Dev-Windup-Project-Information[Windup Project Information] - Github
 repository, IRC, Mailing lists, ...
-* link:Report-Issues-with-Windup[Report Issues with Windup
+* link:Report-Issues-with-Windup[Report Issues with Windup]
 * link:About-the-WINDUP_HOME-Variable[About the WINDUP_HOME Variable]
 
 ==== Get Started
@@ -24,7 +24,7 @@ repository, IRC, Mailing lists, ...
 
 ==== Developer Contributing Information
 
-* link:Dev-Development-Guidelines[Developer Guidelines]
+* link:Dev-Development-Guidelines-and-Conventions[Developer Guidelines and Conventions]
 * link:Dev-Submit-Code-Updates-to-the-Windup-Project[Submit Code Updates to the Windup Project]
 
 ==== Understand the Windup Architecture and Structure

diff --git a/docs/Dev-Build-Windup-from-Source.adoc b/docs/Dev-Build-Windup-from-Source.adoc
@@ -106,7 +106,7 @@ project directory, then click `OK`.
 or dependency errors and click `Finish`. If you get a dialog titled
 _Incomplete Maven Goal Execution_, ignore it and click `OK` to continue.
 . In the Project Explorer tab, find the `windup_parent` project in the
-list, right-mouse, and choose `Run As` --> `Maven install`.
+list, right-click, and choose `Run As` --> `Maven install`.
 
 ==== Extract the Windup Distribution Source File
 

diff --git a/docs/Dev-Classloading-Notes.adoc b/docs/Dev-Classloading-Notes.adoc
@@ -12,6 +12,9 @@ This covers the specific situations when the Windup core developer needs to look
 [source,java]
 --------
 AddonRegistry.getServices(MyServiceInterface.class)
+
+// To get the AddonRegistry, use Windup's FurnaceHolder:
+FurnaceHolder.getFurnace().getAddonRegistry().getServices(MyServiceInterface.class);
 --------
 or
 [source,java]
@@ -27,6 +30,19 @@ If you want something from the current addon, you need to @Inject its ServiceReg
 Depends, if you are in a Furnace Service, then yes, it will use the
 current code's addon's classloader.
 
+==== Reading annotations from classes
+
+Since classes can be proxied by Forge/Furnace, it's safer to read annotations using `Annotations API`:
+
+    Rules annotation = Annotations.getAnnotation(this.getClass(), Rules.class);
+
+Supposedly, Furnace proxies should also be able to handle such call:
+
+    Rules annotation1 = ((FurnaceProxy) proxy).getOriginalClass().getAnnotation(Rules.class);
+
+TODO: Find out how exactly this is done.
+
+
 ==== How do I know if I am in a Furnace service?
 
 Every furnace service is wrapped in a proxy. If it came from another

diff --git a/docs/Dev-Development-Guidelines-and-Conventions.adoc b/docs/Dev-Development-Guidelines-and-Conventions.adoc
@@ -0,0 +1,57 @@
+[[Dev-Development-Guidelines-and-Conventions]]
+=== Development Guidelines and Conventions
+
+* xref:project-source-code-formatting[Project Source Code Formatting]
+* xref:source-code-naming-conventions[Source Code Naming Conventions]
+* xref:maven-project-naming-conventions[Maven Project Naming Conventions]
+
+[[project-source-code-formatting]]
+==== Project Source Code Formatting
+
+All project source code contributed to Windup should be formatted using the settings defined in the `Eclipse_Code_Format_Profile.xml` file located in the root directory of the Windup project.
+
+===== Eclipse IDE
+
+. In Eclipse, choose Windows -> Preferences.
+. Expand Java -> Code Style -> Formatter
+. Click Import
+. Browse to the `Eclipse_Code_Format_Profile.xml` located in the root of the Windup project directory, then click 'OK'.
+
+===== Netbeans IDE
+
+Use this file to format Windup source code: 
+
+http://plugins.netbeans.org/plugin/50877/eclipse-code-formatter-for-java[http://plugins.netbeans.org/plugin/50877/eclipse-code-formatter-for-java] 
+
+===== IntelliJ IDEA
+
+Use this file to format Windup source code: 
+
+http://plugins.jetbrains.com/plugin/?id=6546[http://plugins.jetbrains.com/plugin/?id=6546]
+
+[[source-code-naming-conventions]]
+==== Source Code Naming Conventions
+
+===== Class Interface and Implementation Names
+
+* Do not name interfaces using the prefix 'I' for interface names. Instead, use a descriptive term for the interface, like `Module.java`.
+* The implementation class name should begin with a descriptive name, followed by the interface name, for example, for example `JavaHandlerModule.java`
+
+===== Standard Prefixes and Suffixes
+
+* Append all RuleProvider class names with `RuleProvider`.
+* Append all XML rule file names with `.windup.xml`
+* Append all Model class names with `Model`.
+* All test names should be prefixed with 'Test'.
+* Property constants: TBD 
+
+[[maven-project-naming-conventions]]
+==== Maven Project Naming Conventions
+
+===== Maven Module Names
+
+The following are not really accurate at this time. This is still TBD! 
+
+* Lowercase with dashes. Start with `windup-`.
+* Ruleset addons start with `windup-rules-`.
+
diff --git a/docs/Dev-Troubleshoot-Windup-Issues.adoc b/docs/Dev-Troubleshoot-Windup-Issues.adoc
@@ -19,3 +19,11 @@ See xref:Known-Issues[Known Issues] and https://issues.jboss.org/browse/WINDUP-1
 
 Configuring dependencies in a Forge-based project can be a little tricky.
 See xref:Dev-Dependencies[Dependencies] for some hints.
+
+
+-----
+Caused by: java.lang.IllegalArgumentException: Type value for model 'org.jboss.windup.rules.files.model.FileReferenceModel' is already registered with model org.jboss.windup.rules.files.model.FileReferenceModel
+-----
+
+This means that the model class is loaded twice. I.e. the module containing it is loaded twice. Or, in tests, you may be (accidentally) adding the class to the deployment.
+This may especially happen after Maven coordinates of some module are changed.
diff --git a/docs/Dev-Windup-Documentation-Process.adoc b/docs/Dev-Windup-Documentation-Process.adoc
@@ -12,9 +12,70 @@ Windup product documentation is stored here: https://github.com/windup/windup-do
 
 See the https://github.com/windup/windup-documentation/blob/master/CONTRIBUTING.adoc[CONTRIBUTING guide] for AsciiDoc syntax rules regarding headers and links to make this process easier.
 
-The https://github.com/windup/windup-documentation/tree/master/scripts/windupDocUpdate.sh script copies the pages from the Windup wiki to the windup-documentation repository, makes minor modifications, and generates each guide in a single HTML page book format. The resulting guides are created in the `html/` directory.
+==== Update the Windup Documentation with the Latest Wiki Changes
 
-==== Publish the HTML docs to online docs (at GitHub IO)
+===== Summary
+
+The Windup guides are located in the windup-documentation/docs directory. They are named the same as the guides in the Wiki but have a 'Windup-' prefix. The windup-documentation/docs guides should kept synchronized with the versions in the windup.wiki.
+
+[cols="2*", options="header"] 
+|===
+|Wiki Guide
+|Windup Docs Guide
+
+|User-Guide.asciidoc
+|Windup-User-Guide.adoc
+
+|Rules-Development-Guide.asciidoc
+|Windup-Rules-Development-Guide.adoc
+
+|Core-Development-Guide.asciidoc
+|Windup-Core-Development-Guide.adoc
+
+|Migration-Planning-Guide
+|Windup-Migration-Planning-Guide.adoc
+|===
+
+====== Documentation Update Scripts
+
+The https://github.com/windup/windup-documentation/tree/master/scripts/windupDocUpdate.sh script copies the pages from the Windup wiki to the windup-documentation repository, makes minor modifications, and generates each guide in a single HTML page book format. The resulting guides are created in the `WINDUP_DOCUMENTATION_HOME/html/` directory.
+
+The script performs the following steps.
+
+. Copies the Windup wiki pages to the `WINDUP_DOCUMENTATION_HOME/docs/` directory, renaming them with the `.adoc` extension.
+
+. Makes sure each guide includes all pages that are referenced by pages within it. Scripts are provided to search for links within each individual guide. They navigate to the `WINDUP_DOCUMENTATION_HOME/docs/` directory and search using the following command:
+
+    grep 'xref:[A-Z]' `find . -name '*.adoc'`.
+
+. Replaces each `xref:` to external pages with an `xref:` using the following command.
+
+    find . -name '*.adoc' -print | xargs sed -i 's/xref:/xref:/g'
+
+. Navigates to the `WINDUP_DOCUMENTATION_HOME/` directory and builds the books. The single page HTML files are created in the `WINDUP_DOCUMENTATION_HOME/html/` directory.
+
++
+[cols="2*", options="header"] 
+|===
+|Windup Guide
+|Command
+
+|Windup User Guide
+|asciidoctor -t -dbook -a toc -o html/WindupUserGuide.html docs/Windup-User-Guide.adoc
+
+|Windup Rules Development Guide
+|asciidoctor -t -dbook -a toc -o html/WindupRulesDevelopmentGuide.html docs/Windup-Rules-Development-Guide.adoc
+
+|Windup Core Development Guide
+|asciidoctor -t -dbook -a toc -o html/WindupCoreDevelopmentGuide.html docs/Windup-Core-Development-Guide.adoc
+|===
+
+
+==== Publish the HTML Docs for Access at GitHub IO
+
+The https://github.com/windup/windup-documentation/tree/master/scripts/windupPublish.sh script copies the pages from the Windup wiki to the windup-documentation repository, makes minor modifications, and generates each guide in a single HTML page book format. The resulting guides are created in the `WINDUP_DOCUMENTATION_HOME/html/` directory.
+
+The script performs the following steps.
 
 * The first time, you must fork and clone the windup GitHub repository. After that, just fetch the latest upstream.
 +
@@ -23,35 +84,32 @@ git clone https://github.com/windup/windup.git
 git fetch upstream
 ----
 
-* The first time, you must fork and clone the windup-documentation GitHub repository. After that, just fetch the latest upstream.
-+
-----
-git clone https://github.com/windup/windup-documentation.git
-git fetch upstream
-----
-
-* Navigate to the local windup directory.
+* Navigate to the local `WINDUP_HOME/` directory.
 +
 ----
 cd windup
 ----
 
-* Checkout the gh-pages from the windup repository
+* Checkout the `gh-pages` from the `WINDUP_HOME` repository
 +
 ----
-git checkout -b gh-pages windup
+git checkout -b gh-pages windup/gh-pages
 ----
 
-* If the directory does not yet exist, create a docs/WINDUP-RELEASE-html/ directory.
+* If the `WINDUP_HOME/docs/WINDUP_RELEASE/` directory does not yet exist, create a `docs/WINDUP_RELEASE/html/images/` 
 +
 ----
-mkdir -p docs/2.0.0.VERSION/html (if it doesn't exist!)
+mkdir -p docs/WINDUP_RELEASE/html/images (if it doesn't exist!)
 ----
 
-* Copy any new images, stylesheets, and html files from windup-documentation:
+* Copy any the images, stylesheets, and html files from windup-documentation:
 +
 ----
-cp ../windup-documentation/html/*.html ../windup-documentation/*.css ../windup-documentation/images/* docs/2.0.0.VERSION/html
+
+cp WINDUP_DOCUMENTATION_HOME/html/*.html WINDUP_HOME/docs/WINDUP_RELEASE/html/
+cp WINDUP_DOCUMENTATION_HOME/*.css WINDUP_HOME/docs/WINDUP_RELEASE/html/
+cp WINDUP_DOCUMENTATION_HOME/images/* WINDUP_HOME/docs/WINDUP_RELEASE/html/images/
+
 ----
 
 * Add the updated files to GitHub.
@@ -72,4 +130,35 @@ git commit -m "Update message..."
 git push upstream gh-pages
 ----
 
-* View the documentation at http://windup.github.io/windup/docs/2.0.0.VERSION/html/WindupUserGuide.html
+* View the documentation at http://windup.github.io/windup/docs/WINDUP_RELEASE/html/WindupUserGuide.html
+
+* Update the symlink for `latest` to point to the new version.
+
+** Navigate to the `WINDUP_HOME/docs` directory.
+
+** Remove the existing symlink for "latest".
+
+        unlink latest
+
+** Create a symlink to the new documentation.
+
+        Syntax: ln -s WINDUP_RELEASE latest
+        Example: ln -s 2.0.0.Final latest
+
+** Add the modified "latest" directory to Git.
+
+        git add latest
+
+** Commit the change.
+
+        git commit -m 'Replace symlink for latest to point to 2.0.0.Final'
+
+** Push the changes to your own git repository, verify and issue a pull.
+
+        git push origin HEAD
+
+** Push the changes upstream
+
+        git push upstream gh-pages
+
+** View the documentation at http://windup.github.io/windup/docs/latest/html/WindupUserGuide.html
diff --git a/docs/Execute-Windup.adoc b/docs/Execute-Windup.adoc
@@ -75,7 +75,7 @@ Where:
 +
 *OUTPUT_REPORT_DIRECTORY* is the fully qualified path to the folder that will contain the the report information produced by Windup.
 +
-NOTE: If the *OUTPUT_REPORT_DIRECTORY* directory exists, your are prompted to overwrite the contents. If you respond "y", it is deleted and recreated by Windup, so be careful not to specify an output directory that contains important information!
+NOTE: If the *OUTPUT_REPORT_DIRECTORY* directory exists, you are prompted to overwrite the contents. If you respond "y", it is deleted and recreated by Windup, so be careful not to specify an output directory that contains important information!
 
 +
 *PACKAGE_1*, *PACKAGE_2*, *PACKAGE_N* are the packages to be evaluated by Windup.

diff --git a/docs/Get-Involved.adoc b/docs/Get-Involved.adoc
@@ -31,6 +31,7 @@ Any level of involvement is greatly appreciated!
 ** http://windup.github.io/windup/docs/latest/html/WindupRulesDevelopmentGuide.html
 ** http://windup.github.io/windup/docs/latest/html/WindupCoreDevelopmentGuide.html
 * Windup Forums: https://community.jboss.org/en/windup
+* Windup Forums: https://developer.jboss.org/en/windup (inherited from Windup 0.x)
 * Windup Issue Tracker: https://issues.jboss.org/browse/WINDUP
 * Windup Users Mailing List: windup-users@lists.jboss.org
 * Windup Developers Mailing List: windup-dev@lists.jboss.org

diff --git a/docs/Install-and-Configure-Maven.adoc b/docs/Install-and-Configure-Maven.adoc
@@ -1,11 +1,13 @@
 [[Install-and-Configure-Maven]]
 === Install and Configure Maven
 
+If you plan to contribute to the core code base or create Java-based rule addons, you must first install and configure Maven to build Windup from source.
+
 ==== Download and Install Maven
 
 If you plan to use Eclipse Luna (4.4) to build Windup, you can skip this
-step. This version of Eclipse embeds Maven 3.2.1 so you do not need to
-install it separately. Skip to the section entitled xref:configure-maven-to-build-windup[Configure Maven to Build Windup].
+step and go directly to the section entitled xref:configure-maven-to-build-windup[Configure Maven to Build Windup]. This version of Eclipse embeds Maven 3.2.1 so you do not need to
+install it separately.
 
 If you plan to run Maven using the command line or plan to use Red Hat
 JBoss Developer Studio 7.1.1 or an older version of Eclipse, you must
@@ -80,5 +82,8 @@ ending `</profiles>` element.
 element to make the profile active.
 +
 ----------------------------------------------------------
-    <activeProfile>jboss-nexus-repository</activeProfile> 
-----------------------------------------------------------
+<activeProfile>jboss-nexus-repository</activeProfile> 
+----------------------------------------------------------
+
+You are now configured to build Windup.
+