diff --git a/.travis.yml b/.travis.yml index 06d1b92a..958d94a3 100644 --- a/.travis.yml +++ b/.travis.yml @@ -7,9 +7,8 @@ before_install: - gem install asciidoctor install: #TODO: build docs -- mvn --settings .settings.xml install -U -DskipTests=true -Dmaven.test.redirectTestOutputToFile=true -#- mvn --settings .settings.xml install -P docs -q -U -DskipTests=true -Dmaven.test.redirectTestOutputToFile=true -#- ./docs/src/main/asciidoc/ghpages.sh +- mvn --settings .settings.xml install -P docs -q -U -DskipTests=true -Dmaven.test.redirectTestOutputToFile=true +- ./docs/src/main/asciidoc/ghpages.sh script: - '[ "${TRAVIS_PULL_REQUEST}" != "false" ] || mvn --settings .settings.xml deploy -nsu -Dmaven.test.redirectTestOutputToFile=true' - '[ "${TRAVIS_PULL_REQUEST}" = "false" ] || mvn --settings .settings.xml install -nsu -Dmaven.test.redirectTestOutputToFile=true' diff --git a/README.adoc b/README.adoc new file mode 100644 index 00000000..37917681 --- /dev/null +++ b/README.adoc @@ -0,0 +1,209 @@ +// Do not edit this file (e.g. go instead to src/main/asciidoc) + +image::https://travis-ci.org/spring-cloud/spring-cloud-zookeeper.svg?branch=master[Build Status, link=https://travis-ci.org/spring-cloud/spring-cloud-zookeeper] + +This project provides Zookeeper integrations for Spring Boot apps through autoconfiguration +and binding to the Spring Environment and other Spring programming model idioms. With a few +simple annotations you can quickly enable and configure the common patterns inside your +application and build large distributed systems with Zookeeper based components. The +patterns provided include Service Discovery, Circuit Breaker and Configuration. +Intelligent Routing (Zuul) and Client Side Load Balancing (Ribbon) are provided by +integration with Spring Cloud Netflix. + + +== This is a Developer Preview + +We plan on releasing a milestone shortly. + +== Zookeeper overview + +Features of Zookeeper + +* TODO: list high level features of zookeeper + +See the http://zookeeper.apache.org[Zookeeper site] for more information. Spring Cloud Zookeeper also builds on the http://curator.apache.org[Apache Curator] project which started life at Netflix. + +== Spring Cloud Zookeeper Features + +* Spring Cloud `DiscoveryClient` implementation +** supports Ribbon and Zuul +* Zookeeper based `PropertySource` loaded during the 'bootstrap' phase. + +== Running the sample + +1. TODO: document running the sample + +== Building + +:jdkversion: 1.7 + +=== 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. + + +== Contributing + +Spring Cloud is released under the non-restrictive Apache 2.0 license. If you would like +to contribute something, or simply want to hack on the code this document should help +you get started. + +=== 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 + you can import formatter settings using the + `eclipse-code-formatter.xml` file from the + https://github.com/spring-cloud/build/tree/master/eclipse-coding-conventions.xml[Spring + Cloud Build] project. 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). +* When writing a commit message please follow http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html[these conventions], + if you are fixing an existing issue please add `Fixes gh-XXXX` at the end of the commit + message (where XXXX is the issue number). \ No newline at end of file diff --git a/README.md b/README.md deleted file mode 100644 index 0295cbb9..00000000 --- a/README.md +++ /dev/null @@ -1,17 +0,0 @@ -spring-cloud-zookeeper -=================== - -[![Build Status](https://travis-ci.org/spring-cloud/spring-cloud-zookeeper.svg?branch=master)](https://travis-ci.org/spring-cloud/spring-cloud-zookeeper) - -Developer Preview - -### TODO - -- [X] zookeeper config -- [X] zookeeper service discovery -- [X] zookeeper ribbon load balancer -- [ ] zookeeper ui -- [X] zookeeper property source -- [ ] zookeeper event bus - - [ ] send messages - - [ ] receive messages diff --git a/docs/pom.xml b/docs/pom.xml new file mode 100644 index 00000000..20be4ce0 --- /dev/null +++ b/docs/pom.xml @@ -0,0 +1,45 @@ + + + 4.0.0 + + org.springframework.cloud + spring-cloud-build + 1.0.2.BUILD-SNAPSHOT + + + spring-cloud-zookeeper-docs + pom + Spring Cloud Zookeeper Docs + Spring Cloud Docs + 1.0.0.BUILD-SNAPSHOT + + spring-cloud-zookeeper + ${basedir}/.. + + + + docs + + + + org.asciidoctor + asciidoctor-maven-plugin + false + + + org.apache.maven.plugins + maven-antrun-plugin + false + + + org.codehaus.mojo + build-helper-maven-plugin + false + + + + + + diff --git a/docs/src/main/asciidoc/README.adoc b/docs/src/main/asciidoc/README.adoc new file mode 100644 index 00000000..9064f3a5 --- /dev/null +++ b/docs/src/main/asciidoc/README.adoc @@ -0,0 +1,33 @@ +image::https://travis-ci.org/spring-cloud/spring-cloud-zookeeper.svg?branch=master[Build Status, link=https://travis-ci.org/spring-cloud/spring-cloud-zookeeper] + +include::intro.adoc[] + +== This is a Developer Preview + +We plan on releasing a milestone shortly. + +== Zookeeper overview + +Features of Zookeeper + +* TODO: list high level features of zookeeper + +See the http://zookeeper.apache.org[Zookeeper site] for more information. Spring Cloud Zookeeper also builds on the http://curator.apache.org[Apache Curator] project which started life at Netflix. + +== Spring Cloud Zookeeper Features + +* Spring Cloud `DiscoveryClient` implementation +** supports Ribbon and Zuul +* Zookeeper based `PropertySource` loaded during the 'bootstrap' phase. + +== Running the sample + +1. TODO: document running the sample + +== Building + +include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/building.adoc[] + +== Contributing + +include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/contributing.adoc[] diff --git a/docs/src/main/asciidoc/ghpages.sh b/docs/src/main/asciidoc/ghpages.sh new file mode 100755 index 00000000..91905757 --- /dev/null +++ b/docs/src/main/asciidoc/ghpages.sh @@ -0,0 +1,46 @@ +#!/bin/bash -x + +git remote set-url --push origin `git config remote.origin.url | sed -e 's/^git:/https:/'` + +if ! (git remote set-branches --add origin gh-pages && git fetch -q); then + echo "No gh-pages, so not syncing" + exit 0 +fi + +if ! [ -d docs/target/generated-docs ]; then + echo "No gh-pages sources in docs/target/generated-docs, so not syncing" + exit 0 +fi + +# Stash any outstanding changes +################################################################### +git diff-index --quiet HEAD +dirty=$? +if [ "$dirty" != "0" ]; then git stash; fi + +# Switch to gh-pages branch to sync it with master +################################################################### +git checkout gh-pages + +for f in docs/target/generated-docs/*; do + file=${f#docs/target/generated-docs/*} + if ! git ls-files -i -o --exclude-standard --directory | grep -q ^$file$; then + # Not ignored... + cp -rf $f . + git add -A $file + fi +done + +git commit -a -m "Sync docs from master to gh-pages" + +# Uncomment the following push if you want to auto push to +# the gh-pages branch whenever you commit to master locally. +# This is a little extreme. Use with care! +################################################################### +git push origin gh-pages + +# Finally, switch back to the master branch and exit block +git checkout master +if [ "$dirty" != "0" ]; then git stash pop; fi + +exit 0 diff --git a/docs/src/main/asciidoc/images/.gitkeep b/docs/src/main/asciidoc/images/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/docs/src/main/asciidoc/intro.adoc b/docs/src/main/asciidoc/intro.adoc new file mode 100644 index 00000000..9ac8043e --- /dev/null +++ b/docs/src/main/asciidoc/intro.adoc @@ -0,0 +1,8 @@ +This project provides Zookeeper integrations for Spring Boot apps through autoconfiguration +and binding to the Spring Environment and other Spring programming model idioms. With a few +simple annotations you can quickly enable and configure the common patterns inside your +application and build large distributed systems with Zookeeper based components. The +patterns provided include Service Discovery, Circuit Breaker and Configuration. +Intelligent Routing (Zuul) and Client Side Load Balancing (Ribbon) are provided by +integration with Spring Cloud Netflix. + diff --git a/docs/src/main/asciidoc/spring-cloud-zookeeper.adoc b/docs/src/main/asciidoc/spring-cloud-zookeeper.adoc new file mode 100644 index 00000000..c55e8425 --- /dev/null +++ b/docs/src/main/asciidoc/spring-cloud-zookeeper.adoc @@ -0,0 +1,21 @@ +:github-tag: master +:github-repo: spring-cloud/spring-cloud-zookeeper +:github-raw: http://raw.github.com/{github-repo}/{github-tag} +:github-code: http://github.com/{github-repo}/tree/{github-tag} += Spring Cloud Zookeeper + +include::intro.adoc[] + +[[spring-cloud-zookeeper-install]] +== Install Zookeeper +TODO: document zookeeper installation + +[[spring-cloud-zookeeper-discovery]] +== Service Discovery with Zookeeper + +TODO: document zookeeper service discovery + +[[spring-cloud-zookeeper-config]] +== Distributed Configuration with Zookeeper + +TODO: document zookeeper config diff --git a/docs/src/main/ruby/generate_readme.sh b/docs/src/main/ruby/generate_readme.sh new file mode 100755 index 00000000..79aadce4 --- /dev/null +++ b/docs/src/main/ruby/generate_readme.sh @@ -0,0 +1,30 @@ +#!/usr/bin/env ruby + +base_dir = File.join(File.dirname(__FILE__),'../../..') +src_dir = File.join(base_dir, "/src/main/asciidoc") +require 'asciidoctor' +require 'optparse' + +options = {} +file = "#{src_dir}/README.adoc" + +OptionParser.new do |o| + o.on('-o OUTPUT_FILE', 'Output file (default is stdout)') { |file| options[:to_file] = file unless file=='-' } + o.on('-h', '--help') { puts o; exit } + o.parse! +end + +file = ARGV[0] if ARGV.length>0 + +srcDir = File.dirname(file) +out = "// Do not edit this file (e.g. go instead to src/main/asciidoc)\n\n" +doc = Asciidoctor.load_file file, safe: :safe, parse: false, attributes: 'allow-uri-read' +out << doc.reader.read + +unless options[:to_file] + puts out +else + File.open(options[:to_file],'w+') do |file| + file.write(out) + end +end diff --git a/pom.xml b/pom.xml index 09c653f3..3e5ac4ab 100644 --- a/pom.xml +++ b/pom.xml @@ -35,6 +35,7 @@ spring-cloud-zookeeper-config spring-cloud-zookeeper-discovery spring-cloud-zookeeper-sample + docs