diff --git a/docs/src/main/asciidoc/building-base.adoc b/docs/src/main/asciidoc/building-base.adoc new file mode 100644 index 00000000..2e454eaf --- /dev/null +++ b/docs/src/main/asciidoc/building-base.adoc @@ -0,0 +1,129 @@ +=== Basic Compile and Test + +To build the source you will need to install +http://maven.apache.org/run-maven/index.html[Apache Maven] v3.0.6 or above and JDK {jdkversion}. + +Spring Cloud uses Maven for most build-related activities, and you +should be able to get off the ground quite quickly by cloning the +project you are interested in and typing + +---- +$ mvn install -s .settings.xml +---- + +NOTE: You may need to increase the amount of memory available to Maven by setting +a `MAVEN_OPTS` environment variable with the value `-Xmx512m -XX:MaxPermSize=128m` + +The `.settings.xml` is only required the first time (or after updates +to dependencies). It is there to provide repository declarations so +that those do not need to be hard coded in the project poms. + +For hints on how to build the project look in `.travis.yml` if there +is one. There should be a "script" and maybe "install" command. Also +look at the "services" section to see if any services need to be +running locally (e.g. mongo or rabbit). Ignore the git-related bits +that you might find in "before_install" since they will be able git +credentials and you already have those. + +If you need mongo, rabbit or redis, see the README in the https://github.com/spring-cloud-samples/scripts[scripts +demo repository] for +instructions. For example consider using the "fig.yml" with +http://www.fig.sh/[Fig] to run them in Docker containers. + +=== Documentation + +The spring-cloud-build module has a "docs" profile, and if you switch +that on it will try to build asciidoc sources from +`src/main/asciidoc`. As part of that process it will look for a +`README.adoc` and process it by loading all the includes, but not +parsing or rendering it, just copying it to `${main.basedir}` +(defaults to `${basedir}`, i.e. the root of the project). If there are +any changes in the README it will then show up after a Maven build as +a modified file in the correct place. Just commit it and push the change. + +=== Pull Requests + +Spring Cloud is released under the non-restrictive Apache 2.0 license, +and follows a very standard Github development process, using Github +tracker for issues and merging pull requests into master. If you want +to contribute even something trivial please do not hesitate, but +follow the guidelines below. + +==== Sign the Contributor License Agreement +Before we accept a non-trivial patch or pull request we will need you +to sign the +https://support.springsource.com/spring_committer_signup[contributor's +agreement]. Signing the contributor's agreement does not grant anyone +commit rights to the main repository, but it does mean that we can +accept your contributions, and you will get an author credit if we do. +Active contributors might be asked to join the core team, and given +the ability to merge pull requests. + +==== Code Conventions and Housekeeping +None of these is essential for a pull request, but they will all help. They can also be +added after the original pull request but before a merge. + +* Use the Spring Framework code format conventions. If you use Eclipse and you follow + the ``Importing into eclipse'' instructions below you should get project specific + formatting automatically. You can also import formatter settings using the + `eclipse-code-formatter.xml` file from the `eclipse` folder. If using IntelliJ, you can + use the http://plugins.jetbrains.com/plugin/6546[Eclipse Code Formatter Plugin] + to import the same file. +* Make sure all new `.java` files to have a simple Javadoc class comment with at least an + `@author` tag identifying you, and preferably at least a paragraph on what the class is + for. +* Add the ASF license header comment to all new `.java` files (copy from existing files + in the project) +* Add yourself as an `@author` to the .java files that you modify substantially (more + than cosmetic changes). +* Add some Javadocs and, if you change the namespace, some XSD doc elements. +* A few unit tests would help a lot as well -- someone has to do it. +* If no-one else is using your branch, please rebase it against the current master (or + other target branch in the main project). + +=== Working with the code +If you don't have an IDE preference we would recommend that you use +http://www.springsource.com/developer/sts[Spring Tools Suite] or +http://eclipse.org[Eclipse] when working with the code. We use the +http://eclipse.org/m2e/[m2eclipe] eclipse plugin for maven support. Other IDEs and tools +should also work without issue. + +==== Importing into eclipse with m2eclipse +We recommend the http://eclipse.org/m2e/[m2eclipe] eclipse plugin when working with +eclipse. If you don't already have m2eclipse installed it is available from the "eclipse +marketplace". + +==== Importing into eclipse without m2eclipse +If you prefer not to use m2eclipse you can generate eclipse project metadata using the +following command: + +[indent=0] +---- + $ mvn eclipse:eclipse +---- + +The generated eclipse projects can be imported by selecting `import existing projects` +from the `file` menu. + +==== Adding Project Lombok Agent + +Spring Cloud uses [Project +Lombok](http://projectlombok.org/features/index.html) to generate +getters and setters etc. Compiling from the command line this +shouldn't cause any problems, but in an IDE you need to add an agent +to the JVM. Full instructions can be found in the Lombok website. The +sign that you need to do this is a lot of compiler errors to do with +missing methods and fields, e.g. + +[indent=0] +---- +The method getInitialStatus() is undefined for the type EurekaInstanceConfigBean EurekaDiscoveryClientConfiguration.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka line 120 Java Problem +The method getInitialStatus() is undefined for the type EurekaInstanceConfigBean EurekaDiscoveryClientConfiguration.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka line 121 Java Problem +The method setNonSecurePort(int) is undefined for the type EurekaInstanceConfigBean EurekaDiscoveryClientConfiguration.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka line 112 Java Problem +The type EurekaInstanceConfigBean.IdentifyingDataCenterInfo must implement the inherited abstract method DataCenterInfo.getName() EurekaInstanceConfigBean.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka line 131 Java Problem +The method getId() is undefined for the type ProxyRouteLocator.ProxyRouteSpec PreDecorationFilter.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/zuul/filters/pre line 60 Java Problem +The method getLocation() is undefined for the type ProxyRouteLocator.ProxyRouteSpec PreDecorationFilter.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/zuul/filters/pre line 55 Java Problem +---- + +==== Importing into other IDEs +Maven is well supported by most Java IDEs. Refer to you vendor documentation. diff --git a/docs/src/main/asciidoc/building-jdk8.adoc b/docs/src/main/asciidoc/building-jdk8.adoc new file mode 100644 index 00000000..e0e1452d --- /dev/null +++ b/docs/src/main/asciidoc/building-jdk8.adoc @@ -0,0 +1,4 @@ +:jdkversion: 1.8 + +include::building-base.adoc[] + diff --git a/docs/src/main/asciidoc/building.adoc b/docs/src/main/asciidoc/building.adoc index 98d78bc4..9a671f42 100644 --- a/docs/src/main/asciidoc/building.adoc +++ b/docs/src/main/asciidoc/building.adoc @@ -1,129 +1,4 @@ -=== Basic Compile and Test +:jdkversion: 1.7 -To build the source you will need to install -http://maven.apache.org/run-maven/index.html[Apache Maven] v3.0.6 or above and JDK 1.7. +include::building-base.adoc[] -Spring Cloud uses Maven for most build-related activities, and you -should be able to get off the ground quite quickly by cloning the -project you are interested in and typing - ----- -$ mvn install -s .settings.xml ----- - -NOTE: You may need to increase the amount of memory available to Maven by setting -a `MAVEN_OPTS` environment variable with the value `-Xmx512m -XX:MaxPermSize=128m` - -The `.settings.xml` is only required the first time (or after updates -to dependencies). It is there to provide repository declarations so -that those do not need to be hard coded in the project poms. - -For hints on how to build the project look in `.travis.yml` if there -is one. There should be a "script" and maybe "install" command. Also -look at the "services" section to see if any services need to be -running locally (e.g. mongo or rabbit). Ignore the git-related bits -that you might find in "before_install" since they will be able git -credentials and you already have those. - -If you need mongo, rabbit or redis, see the README in the https://github.com/spring-cloud-samples/scripts[scripts -demo repository] for -instructions. For example consider using the "fig.yml" with -http://www.fig.sh/[Fig] to run them in Docker containers. - -=== Documentation - -The spring-cloud-build module has a "docs" profile, and if you switch -that on it will try to build asciidoc sources from -`src/main/asciidoc`. As part of that process it will look for a -`README.adoc` and process it by loading all the includes, but not -parsing or rendering it, just copying it to `${main.basedir}` -(defaults to `${basedir}`, i.e. the root of the project). If there are -any changes in the README it will then show up after a Maven build as -a modified file in the correct place. Just commit it and push the change. - -=== Pull Requests - -Spring Cloud is released under the non-restrictive Apache 2.0 license, -and follows a very standard Github development process, using Github -tracker for issues and merging pull requests into master. If you want -to contribute even something trivial please do not hesitate, but -follow the guidelines below. - -==== Sign the Contributor License Agreement -Before we accept a non-trivial patch or pull request we will need you -to sign the -https://support.springsource.com/spring_committer_signup[contributor's -agreement]. Signing the contributor's agreement does not grant anyone -commit rights to the main repository, but it does mean that we can -accept your contributions, and you will get an author credit if we do. -Active contributors might be asked to join the core team, and given -the ability to merge pull requests. - -==== Code Conventions and Housekeeping -None of these is essential for a pull request, but they will all help. They can also be -added after the original pull request but before a merge. - -* Use the Spring Framework code format conventions. If you use Eclipse and you follow - the ``Importing into eclipse'' instructions below you should get project specific - formatting automatically. You can also import formatter settings using the - `eclipse-code-formatter.xml` file from the `eclipse` folder. If using IntelliJ, you can - use the http://plugins.jetbrains.com/plugin/6546[Eclipse Code Formatter Plugin] - to import the same file. -* Make sure all new `.java` files to have a simple Javadoc class comment with at least an - `@author` tag identifying you, and preferably at least a paragraph on what the class is - for. -* Add the ASF license header comment to all new `.java` files (copy from existing files - in the project) -* Add yourself as an `@author` to the .java files that you modify substantially (more - than cosmetic changes). -* Add some Javadocs and, if you change the namespace, some XSD doc elements. -* A few unit tests would help a lot as well -- someone has to do it. -* If no-one else is using your branch, please rebase it against the current master (or - other target branch in the main project). - -=== Working with the code -If you don't have an IDE preference we would recommend that you use -http://www.springsource.com/developer/sts[Spring Tools Suite] or -http://eclipse.org[Eclipse] when working with the code. We use the -http://eclipse.org/m2e/[m2eclipe] eclipse plugin for maven support. Other IDEs and tools -should also work without issue. - -==== Importing into eclipse with m2eclipse -We recommend the http://eclipse.org/m2e/[m2eclipe] eclipse plugin when working with -eclipse. If you don't already have m2eclipse installed it is available from the "eclipse -marketplace". - -==== Importing into eclipse without m2eclipse -If you prefer not to use m2eclipse you can generate eclipse project metadata using the -following command: - -[indent=0] ----- - $ mvn eclipse:eclipse ----- - -The generated eclipse projects can be imported by selecting `import existing projects` -from the `file` menu. - -==== Adding Project Lombok Agent - -Spring Cloud uses [Project -Lombok](http://projectlombok.org/features/index.html) to generate -getters and setters etc. Compiling from the command line this -shouldn't cause any problems, but in an IDE you need to add an agent -to the JVM. Full instructions can be found in the Lombok website. The -sign that you need to do this is a lot of compiler errors to do with -missing methods and fields, e.g. - -[indent=0] ----- -The method getInitialStatus() is undefined for the type EurekaInstanceConfigBean EurekaDiscoveryClientConfiguration.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka line 120 Java Problem -The method getInitialStatus() is undefined for the type EurekaInstanceConfigBean EurekaDiscoveryClientConfiguration.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka line 121 Java Problem -The method setNonSecurePort(int) is undefined for the type EurekaInstanceConfigBean EurekaDiscoveryClientConfiguration.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka line 112 Java Problem -The type EurekaInstanceConfigBean.IdentifyingDataCenterInfo must implement the inherited abstract method DataCenterInfo.getName() EurekaInstanceConfigBean.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/eureka line 131 Java Problem -The method getId() is undefined for the type ProxyRouteLocator.ProxyRouteSpec PreDecorationFilter.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/zuul/filters/pre line 60 Java Problem -The method getLocation() is undefined for the type ProxyRouteLocator.ProxyRouteSpec PreDecorationFilter.java /spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/zuul/filters/pre line 55 Java Problem ----- - -==== Importing into other IDEs -Maven is well supported by most Java IDEs. Refer to you vendor documentation.