buildmaster
7 years ago
1 changed files with 159 additions and 0 deletions
@ -0,0 +1,159 @@
@@ -0,0 +1,159 @@
|
||||
// Do not edit this file (e.g. go instead to src/main/asciidoc) |
||||
|
||||
image::https://circleci.com/gh/spring-cloud/spring-cloud-commons.svg?style=svg[Build Status, link=https://circleci.com/gh/spring-cloud/spring-cloud-commons] |
||||
|
||||
|
||||
http://pivotal.io/platform-as-a-service/migrating-to-cloud-native-application-architectures-ebook[Cloud Native] is a style of application development that encourages easy adoption of best practices in the areas of continuous delivery and value-driven development. |
||||
A related discipline is that of building http://12factor.net/[12-factor Applications], in which development practices are aligned with delivery and operations goals -- for instance, by using declarative programming and management and monitoring. |
||||
Spring Cloud facilitates these styles of development in a number of specific ways. |
||||
The starting point is a set of features to which all components in a distributed system need easy access. |
||||
|
||||
Many of those features are covered by http://projects.spring.io/spring-boot[Spring Boot], on which Spring Cloud builds. Some more features are delivered by Spring Cloud as two libraries: Spring Cloud Context and Spring Cloud Commons. |
||||
Spring Cloud Context provides utilities and special services for the `ApplicationContext` of a Spring Cloud application (bootstrap context, encryption, refresh scope, and environment endpoints). Spring Cloud Commons is a set of abstractions and common classes used in different Spring Cloud implementations (such as Spring Cloud Netflix and Spring Cloud Consul). |
||||
|
||||
If you get an exception due to "Illegal key size" and you use Sun's JDK, you need to install the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files. |
||||
See the following links for more information: |
||||
|
||||
* http://www.oracle.com/technetwork/java/javase/downloads/jce-6-download-429243.html[Java 6 JCE] |
||||
* http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html[Java 7 JCE] |
||||
* http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html[Java 8 JCE] |
||||
|
||||
Extract the files into the JDK/jre/lib/security folder for whichever version of JRE/JDK x64/x86 you use. |
||||
|
||||
== Building |
||||
|
||||
:jdkversion: 1.7 |
||||
|
||||
=== Basic Compile and Test |
||||
|
||||
To build the source you will need to install 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 |
||||
|
||||
---- |
||||
$ ./mvnw install |
||||
---- |
||||
|
||||
NOTE: You can also install Maven (>=3.3.3) yourself and run the `mvn` command |
||||
in place of `./mvnw` in the examples below. If you do that you also |
||||
might need to add `-P spring` if your local Maven settings do not |
||||
contain repository declarations for spring pre-release artifacts. |
||||
|
||||
NOTE: Be aware that you might need to increase the amount of memory |
||||
available to Maven by setting a `MAVEN_OPTS` environment variable with |
||||
a value like `-Xmx512m -XX:MaxPermSize=128m`. We try to cover this in |
||||
the `.mvn` configuration, so if you find you have to do it to make a |
||||
build succeed, please raise a ticket to get the settings added to |
||||
source control. |
||||
|
||||
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're related to setting git |
||||
credentials and you already have those. |
||||
|
||||
The projects that require middleware generally include a |
||||
`docker-compose.yml`, so consider using |
||||
http://compose.docker.io/[Docker Compose] to run the middeware servers |
||||
in Docker containers. See the README in the |
||||
https://github.com/spring-cloud-samples/scripts[scripts demo |
||||
repository] for specific instructions about the common cases of mongo, |
||||
rabbit and redis. |
||||
|
||||
NOTE: If all else fails, build with the command from `.travis.yml` (usually |
||||
`./mvnw install`). |
||||
|
||||
=== 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. |
||||
|
||||
=== 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/[m2eclipse] eclipse plugin for maven support. Other IDEs and tools |
||||
should also work without issue as long as they use Maven 3.3.3 or better. |
||||
|
||||
==== Importing into eclipse with m2eclipse |
||||
We recommend the http://eclipse.org/m2e/[m2eclipse] eclipse plugin when working with |
||||
eclipse. If you don't already have m2eclipse installed it is available from the "eclipse |
||||
marketplace". |
||||
|
||||
NOTE: Older versions of m2e do not support Maven 3.3, so once the |
||||
projects are imported into Eclipse you will also need to tell |
||||
m2eclipse to use the right profile for the projects. If you |
||||
see many different errors related to the POMs in the projects, check |
||||
that you have an up to date installation. If you can't upgrade m2e, |
||||
add the "spring" profile to your `settings.xml`. Alternatively you can |
||||
copy the repository settings from the "spring" profile of the parent |
||||
pom into your `settings.xml`. |
||||
|
||||
==== Importing into eclipse without m2eclipse |
||||
If you prefer not to use m2eclipse you can generate eclipse project metadata using the |
||||
following command: |
||||
|
||||
[indent=0] |
||||
---- |
||||
$ ./mvnw eclipse:eclipse |
||||
---- |
||||
|
||||
The generated eclipse projects can be imported by selecting `import existing projects` |
||||
from the `file` menu. |
||||
|
||||
|
||||
== Contributing |
||||
|
||||
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://cla.pivotal.io/sign/spring[Contributor License 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 of Conduct |
||||
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 |
||||
conduct]. By participating, you are expected to uphold this code. Please report |
||||
unacceptable behavior to spring-code-of-conduct@pivotal.io. |
||||
|
||||
=== 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://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-dependencies-parent/eclipse-code-formatter.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). |
||||
Loading…
Reference in new issue