|
| 1 | +// Do not edit this file (e.g. go instead to src/main/asciidoc) |
| 2 | + |
| 3 | +image::https://circleci.com/gh/spring-cloud/spring-cloud-netflix/tree/master.svg?style=svg["CircleCI", link="https://circleci.com/gh/spring-cloud/spring-cloud-netflix/tree/master"] |
| 4 | +image::https://codecov.io/gh/spring-cloud/spring-cloud-netflix/branch/master/graph/badge.svg["Codecov", link="https://codecov.io/gh/spring-cloud/spring-cloud-netflix/branch/master"] |
| 5 | +image::https://api.codacy.com/project/badge/Grade/a6885a06921e4f72a0df0b7aabd6d118["Codacy code quality", link="https://www.codacy.com/app/Spring-Cloud/spring-cloud-netflix?utm_source=github.com&utm_medium=referral&utm_content=spring-cloud/spring-cloud-netflix&utm_campaign=Badge_Grade"] |
| 6 | + |
| 7 | + |
| 8 | +This project provides Netflix OSS integrations for Spring Boot apps through autoconfiguration |
| 9 | +and binding to the Spring Environment and other Spring programming model idioms. With a few |
| 10 | +simple annotations you can quickly enable and configure the common patterns inside your |
| 11 | +application and build large distributed systems with battle-tested Netflix components. The |
| 12 | +patterns provided include Service Discovery (Eureka), Circuit Breaker (Hystrix), |
| 13 | +Intelligent Routing (Zuul) and Client Side Load Balancing (Ribbon). |
| 14 | + |
| 15 | + |
| 16 | +== Features |
| 17 | + |
| 18 | +* Service Discovery: Eureka instances can be registered and clients can discover the instances using Spring-managed beans |
| 19 | +* Service Discovery: an embedded Eureka server can be created with declarative Java configuration |
| 20 | +* Circuit Breaker: Hystrix clients can be built with a simple annotation-driven method decorator |
| 21 | +* Circuit Breaker: embedded Hystrix dashboard with declarative Java configuration |
| 22 | +* Client Side Load Balancer: Ribbon |
| 23 | +* External Configuration: a bridge from the Spring Environment to Archaius (enables native configuration of Netflix components using Spring Boot conventions) |
| 24 | +* Router and Filter: automatic registration of Zuul filters, and a simple convention over configuration approach to reverse proxy creation |
| 25 | + |
| 26 | +== Building |
| 27 | + |
| 28 | +:jdkversion: 1.8 |
| 29 | + |
| 30 | +=== Basic Compile and Test |
| 31 | + |
| 32 | +To build the source you will need to install JDK {jdkversion}. |
| 33 | + |
| 34 | +Spring Cloud uses Maven for most build-related activities, and you |
| 35 | +should be able to get off the ground quite quickly by cloning the |
| 36 | +project you are interested in and typing |
| 37 | + |
| 38 | +---- |
| 39 | +$ ./mvnw install |
| 40 | +---- |
| 41 | + |
| 42 | +NOTE: You can also install Maven (>=3.3.3) yourself and run the `mvn` command |
| 43 | +in place of `./mvnw` in the examples below. If you do that you also |
| 44 | +might need to add `-P spring` if your local Maven settings do not |
| 45 | +contain repository declarations for spring pre-release artifacts. |
| 46 | + |
| 47 | +NOTE: Be aware that you might need to increase the amount of memory |
| 48 | +available to Maven by setting a `MAVEN_OPTS` environment variable with |
| 49 | +a value like `-Xmx512m -XX:MaxPermSize=128m`. We try to cover this in |
| 50 | +the `.mvn` configuration, so if you find you have to do it to make a |
| 51 | +build succeed, please raise a ticket to get the settings added to |
| 52 | +source control. |
| 53 | + |
| 54 | +For hints on how to build the project look in `.travis.yml` if there |
| 55 | +is one. There should be a "script" and maybe "install" command. Also |
| 56 | +look at the "services" section to see if any services need to be |
| 57 | +running locally (e.g. mongo or rabbit). Ignore the git-related bits |
| 58 | +that you might find in "before_install" since they're related to setting git |
| 59 | +credentials and you already have those. |
| 60 | + |
| 61 | +The projects that require middleware generally include a |
| 62 | +`docker-compose.yml`, so consider using |
| 63 | +http://compose.docker.io/[Docker Compose] to run the middeware servers |
| 64 | +in Docker containers. See the README in the |
| 65 | +https://github.com/spring-cloud-samples/scripts[scripts demo |
| 66 | +repository] for specific instructions about the common cases of mongo, |
| 67 | +rabbit and redis. |
| 68 | + |
| 69 | +NOTE: If all else fails, build with the command from `.travis.yml` (usually |
| 70 | +`./mvnw install`). |
| 71 | + |
| 72 | +=== Documentation |
| 73 | + |
| 74 | +The spring-cloud-build module has a "docs" profile, and if you switch |
| 75 | +that on it will try to build asciidoc sources from |
| 76 | +`src/main/asciidoc`. As part of that process it will look for a |
| 77 | +`README.adoc` and process it by loading all the includes, but not |
| 78 | +parsing or rendering it, just copying it to `${main.basedir}` |
| 79 | +(defaults to `${basedir}`, i.e. the root of the project). If there are |
| 80 | +any changes in the README it will then show up after a Maven build as |
| 81 | +a modified file in the correct place. Just commit it and push the change. |
| 82 | + |
| 83 | +=== Working with the code |
| 84 | +If you don't have an IDE preference we would recommend that you use |
| 85 | +http://www.springsource.com/developer/sts[Spring Tools Suite] or |
| 86 | +http://eclipse.org[Eclipse] when working with the code. We use the |
| 87 | +http://eclipse.org/m2e/[m2eclipse] eclipse plugin for maven support. Other IDEs and tools |
| 88 | +should also work without issue as long as they use Maven 3.3.3 or better. |
| 89 | + |
| 90 | +==== Importing into eclipse with m2eclipse |
| 91 | +We recommend the http://eclipse.org/m2e/[m2eclipse] eclipse plugin when working with |
| 92 | +eclipse. If you don't already have m2eclipse installed it is available from the "eclipse |
| 93 | +marketplace". |
| 94 | + |
| 95 | +NOTE: Older versions of m2e do not support Maven 3.3, so once the |
| 96 | +projects are imported into Eclipse you will also need to tell |
| 97 | +m2eclipse to use the right profile for the projects. If you |
| 98 | +see many different errors related to the POMs in the projects, check |
| 99 | +that you have an up to date installation. If you can't upgrade m2e, |
| 100 | +add the "spring" profile to your `settings.xml`. Alternatively you can |
| 101 | +copy the repository settings from the "spring" profile of the parent |
| 102 | +pom into your `settings.xml`. |
| 103 | + |
| 104 | +==== Importing into eclipse without m2eclipse |
| 105 | +If you prefer not to use m2eclipse you can generate eclipse project metadata using the |
| 106 | +following command: |
| 107 | + |
| 108 | +[indent=0] |
| 109 | +---- |
| 110 | + $ ./mvnw eclipse:eclipse |
| 111 | +---- |
| 112 | + |
| 113 | +The generated eclipse projects can be imported by selecting `import existing projects` |
| 114 | +from the `file` menu. |
| 115 | + |
| 116 | + |
| 117 | + |
| 118 | +== Contributing |
| 119 | + |
| 120 | +Spring Cloud is released under the non-restrictive Apache 2.0 license, |
| 121 | +and follows a very standard Github development process, using Github |
| 122 | +tracker for issues and merging pull requests into master. If you want |
| 123 | +to contribute even something trivial please do not hesitate, but |
| 124 | +follow the guidelines below. |
| 125 | + |
| 126 | +=== Sign the Contributor License Agreement |
| 127 | +Before we accept a non-trivial patch or pull request we will need you to sign the |
| 128 | +https://cla.pivotal.io/sign/spring[Contributor License Agreement]. |
| 129 | +Signing the contributor's agreement does not grant anyone commit rights to the main |
| 130 | +repository, but it does mean that we can accept your contributions, and you will get an |
| 131 | +author credit if we do. Active contributors might be asked to join the core team, and |
| 132 | +given the ability to merge pull requests. |
| 133 | + |
| 134 | +=== Code of Conduct |
| 135 | +This project adheres to the Contributor Covenant https://github.com/spring-cloud/spring-cloud-build/blob/master/docs/src/main/asciidoc/code-of-conduct.adoc[code of |
| 136 | +conduct]. By participating, you are expected to uphold this code. Please report |
| 137 | +unacceptable behavior to spring-code-of-conduct@pivotal.io. |
| 138 | + |
| 139 | +=== Code Conventions and Housekeeping |
| 140 | +None of these is essential for a pull request, but they will all help. They can also be |
| 141 | +added after the original pull request but before a merge. |
| 142 | + |
| 143 | +* Use the Spring Framework code format conventions. If you use Eclipse |
| 144 | + you can import formatter settings using the |
| 145 | + `eclipse-code-formatter.xml` file from the |
| 146 | + https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-dependencies-parent/eclipse-code-formatter.xml[Spring |
| 147 | + Cloud Build] project. If using IntelliJ, you can use the |
| 148 | + http://plugins.jetbrains.com/plugin/6546[Eclipse Code Formatter |
| 149 | + Plugin] to import the same file. |
| 150 | +* Make sure all new `.java` files to have a simple Javadoc class comment with at least an |
| 151 | + `@author` tag identifying you, and preferably at least a paragraph on what the class is |
| 152 | + for. |
| 153 | +* Add the ASF license header comment to all new `.java` files (copy from existing files |
| 154 | + in the project) |
| 155 | +* Add yourself as an `@author` to the .java files that you modify substantially (more |
| 156 | + than cosmetic changes). |
| 157 | +* Add some Javadocs and, if you change the namespace, some XSD doc elements. |
| 158 | +* A few unit tests would help a lot as well -- someone has to do it. |
| 159 | +* If no-one else is using your branch, please rebase it against the current master (or |
| 160 | + other target branch in the main project). |
| 161 | +* When writing a commit message please follow http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html[these conventions], |
| 162 | + if you are fixing an existing issue please add `Fixes gh-XXXX` at the end of the commit |
| 163 | + message (where XXXX is the issue number). |
0 commit comments