Skip to content

Commit cd630bd

Browse files
mp911demp911de
committed
DATAKV-270 - Revise readme for a consistent structure.
1 parent 0577999 commit cd630bd

File tree

2 files changed

+147
-87
lines changed

2 files changed

+147
-87
lines changed

‎CI.adoc

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
= Continuous Integration
2+
3+
image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-keyvalue%2Fmaster&subject=Moore%20(master)[link=https://jenkins.spring.io/view/SpringData/job/spring-data-keyvalue/]
4+
image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-keyvalue%2F2.1.x&subject=Lovelace%20(2.1.x)[link=https://jenkins.spring.io/view/SpringData/job/spring-data-keyvalue/]
5+
image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-keyvalue%2F1.2.x&subject=Ingalls%20(1.2.x)[link=https://jenkins.spring.io/view/SpringData/job/spring-data-keyvalue/]
6+
7+
== Running CI tasks locally
8+
9+
Since this pipeline is purely Docker-based, it's easy to:
10+
11+
* Debug what went wrong on your local machine.
12+
* Test out a a tweak to your `test.sh` script before sending it out.
13+
* Experiment against a new image before submitting your pull request.
14+
15+
All of these use cases are great reasons to essentially run what the CI server does on your local machine.
16+
17+
IMPORTANT: To do this you must have Docker installed on your machine.
18+
19+
1. `docker run -it --mount type=bind,source="$(pwd)",target=/spring-data-keyvalue-github adoptopenjdk/openjdk8:latest /bin/bash`
20+
+
21+
This will launch the Docker image and mount your source code at `spring-data-keyvalue-github`.
22+
+
23+
2. `cd spring-data-keyvalue-github`
24+
+
25+
Next, run your tests from inside the container:
26+
+
27+
3. `./mvnw clean dependency:list test -Dsort` (or whatever profile you need to test out)
28+
29+
Since the container is binding to your source, you can make edits from your IDE and continue to run build jobs.
30+
31+
If you test building the artifact, do this:
32+
33+
1. `docker run -it --mount type=bind,source="$(pwd)",target=/spring-data-keyvalue-github adoptopenjdk/openjdk8:latest /bin/bash`
34+
+
35+
This will launch the Docker image and mount your source code at `spring-data-keyvalue-github`.
36+
+
37+
2. `cd spring-data-keyvalue-github`
38+
+
39+
Next, try to package everything up from inside the container:
40+
+
41+
3. `./mvnw -Pci,snapshot -Dmaven.test.skip=true clean package`
42+
43+
NOTE: Docker containers can eat up disk space fast! From time to time, run `docker system prune` to clean out old images.

‎README.adoc

+104-87
Original file line numberDiff line numberDiff line change
@@ -1,136 +1,153 @@
1-
image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-keyvalue%2Fmaster&subject=Moore%20(master)[link=https://jenkins.spring.io/view/SpringData/job/spring-data-keyvalue/]
2-
image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-keyvalue%2F2.1.x&subject=Lovelace%20(2.1.x)[link=https://jenkins.spring.io/view/SpringData/job/spring-data-keyvalue/]
3-
image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-keyvalue%2F1.2.x&subject=Ingalls%20(1.2.x)[link=https://jenkins.spring.io/view/SpringData/job/spring-data-keyvalue/]
1+
= Spring Data KeyValue image:https://jenkins.spring.io/buildStatus/icon?job=spring-data-keyvalue%2Fmaster&subject=Build[link=https://jenkins.spring.io/view/SpringData/job/spring-data-keyvalue/] https://gitter.im/spring-projects/spring-data[image:https://badges.gitter.im/spring-projects/spring-data.svg[Gitter]]
42

5-
# Spring Data Key Value
3+
The primary goal of the https://projects.spring.io/spring-data[Spring Data] project is to make it easier to build Spring-powered applications that use new data access technologies such as non-relational databases, map-reduce frameworks, and cloud based data services.
64

7-
The primary goal of the https://projects.spring.io/spring-data[Spring Data] project is to make it easier to build Spring-powered applications that use data access technologies. This module provides infrastructure components to build repository abstractions for stores dealing with Key/Value pairs and ships with a default `java.util.Map` based implementation.
5+
This module provides infrastructure components to build repository abstractions for stores dealing with Key/Value pairs and ships with a default `java.util.Map` based implementation.
86

9-
## Features
7+
== Features
108

119
* Infrastructure for building repositories on top of key/value implementations.
1210
* Dynamic SpEL query generation from query method names.
1311
* Possibility to integrate custom repository code.
1412

13+
== Code of Conduct
1514

16-
## Quick Start
15+
This project is governed by the link:CODE_OF_CONDUCT.adoc[Spring Code of Conduct]. By participating, you are expected to uphold this code of conduct. Please report unacceptable behavior to [email protected].
1716

18-
Download the jar through Maven:
17+
== Getting Started
1918

20-
[source, xml]
21-
----
22-
<dependency>
23-
<groupId>org.springframework.data</groupId>
24-
<artifactId>spring-data-keyvalue</artifactId>
25-
<version>${version}</version>
26-
</dependency>
19+
Here is a quick teaser of an application using Spring Data Repositories in Java:
20+
21+
[source,java]
2722
----
23+
public interface PersonRepository extends CrudRepository<Person, Long> {
2824
29-
For snapshot versions, make sure you include the spring snapshots repository:
25+
List<Person> findByLastname(String lastname);
3026
31-
[source, xml]
32-
----
33-
<repositories>
34-
<repository>
35-
<id>spring-libs-snapshot</id>
36-
<url>https://repo.spring.io/libs-snapshot</url>
37-
</repository>
38-
</repositories>
39-
----
27+
List<Person> findByFirstnameLike(String firstname);
28+
}
4029
41-
The `ConcurrentHashMap` based default configuration looks like this:
30+
@Service
31+
public class MyService {
4232
43-
[source, java]
44-
----
45-
@Configuration
46-
@EnableMapRepositories("com.acme.repositories")
47-
class AppConfig { … }
48-
----
33+
private final PersonRepository repository;
4934
50-
NOTE: it is possible to change the used `java.util.Map` implementation via `@EnableMapRepositories(mapType=….class)`.
35+
public MyService(PersonRepository repository) {
36+
this.repository = repository;
37+
}
5138
52-
Create the domain type and use `@KeySpace` to explicitly group values into one region. By default, the type class name is used.
39+
public void doWork() {
5340
54-
[source, java]
55-
----
56-
@KeySpace("user")
57-
class User {
41+
repository.deleteAll();
42+
43+
Person person = new Person();
44+
person.setFirstname("Oliver");
45+
person.setLastname("Gierke");
46+
repository.save(person);
47+
48+
List<Person> lastNameResults = repository.findByLastname("Gierke");
49+
List<Person> firstNameResults = repository.findByFirstnameLike("Oli*");
50+
}
51+
}
52+
53+
@KeySpace("person")
54+
class Person {
5855
5956
@Id String uuid;
6057
String firstname;
58+
String lastname;
59+
60+
// getters and setters omitted for brevity
6161
}
62+
63+
@Configuration
64+
@EnableMapRepositories("com.acme.repositories")
65+
class AppConfig { … }
6266
----
6367

64-
Create a repository interface in `com.acme.repositories`:
68+
=== Maven configuration
69+
70+
Add the Maven dependency:
6571

66-
[source, java]
72+
[source,xml]
6773
----
68-
public interface UserRepository extends CrudRepository<User, String> {
69-
List<String> findByLastname(String lastname);
70-
}
74+
<dependency>
75+
<groupId>org.springframework.data</groupId>
76+
<artifactId>spring-data-keyvalue</artifactId>
77+
<version>${version}.RELEASE</version>
78+
</dependency>
7179
----
7280

73-
## QueryDSL
81+
If you'd rather like the latest snapshots of the upcoming major version, use our Maven snapshot repository and declare the appropriate dependency version.
7482

75-
To use Querydsl with Spring Data KeyValue repositories, `com.mysema.querydsl:querydsl-collections:3.6.0` (or better) needs to be present on the classpath. Just add `QueryDslPredicateExecutor` to the repository definition and use `com.mysema.query.types.Predicate` to define the query.
83+
[source,xml]
84+
----
85+
<dependency>
86+
<groupId>org.springframework.data</groupId>
87+
<artifactId>spring-data-keyvalue</artifactId>
88+
<version>${version}.BUILD-SNAPSHOT</version>
89+
</dependency>
7690
91+
<repository>
92+
<id>spring-libs-snapshot</id>
93+
<name>Spring Snapshot Repository</name>
94+
<url>https://repo.spring.io/libs-snapshot</url>
95+
</repository>
96+
----
7797

78-
## Tips
79-
To have the maximum performance we encourage you to use the latest Spring 4.1.x or better release with compiled SpEL expressions enabled.
98+
== Getting Help
8099

81-
[source, bash]
82-
----
83-
-Dspring.expression.compiler.mode=IMMEDIATE
84-
----
100+
Having trouble with Spring Data? We’d love to help!
85101

102+
* Check the
103+
https://docs.spring.io/spring-data/keyvalue/docs/current/reference/html/[reference documentation], and https://docs.spring.io/spring-data/keyvalue/docs/current/api/[Javadocs].
104+
* Learn the Spring basics – Spring Data builds on Spring Framework, check the https://spring.io[spring.io] web-site for a wealth of reference documentation.
105+
If you are just starting out with Spring, try one of the https://spring.io/guides[guides].
106+
* If you are upgrading, check out the https://docs.spring.io/spring-data/keyvalue/docs/current/changelog.txt[changelog] for "`new and noteworthy`" features.
107+
* Ask a question - we monitor https://stackoverflow.com[stackoverflow.com] for questions tagged with https://stackoverflow.com/tags/spring-data[`spring-data-keyvalue`].
108+
You can also chat with the community on https://gitter.im/spring-projects/spring-data[Gitter].
109+
* Report bugs with Spring Data KeyValue at https://jira.spring.io/browse/DATAKV[jira.spring.io/browse/DATAKV].
86110

87-
## Contributing to Spring Data Key Value
111+
== Reporting Issues
88112

89-
Here are some ways for you to get involved in the community:
113+
Spring Data uses JIRA as issue tracking system to record bugs and feature requests. If you want to raise an issue, please follow the recommendations below:
90114

91-
* Get involved with the Spring community by helping out on https://stackoverflow.com/questions/tagged/spring-data-keyvalue[stackoverflow] by responding to questions and joining the debate.
92-
* Create https://jira.spring.io/browse/DATAKV[JIRA] tickets for bugs and new features and comment and vote on the ones that you are interested in.
93-
* Github is for social coding: if you want to write code, we encourage contributions through pull requests from https://help.github.com/forking[forks of this repository]. If you want to contribute code this way, please reference a JIRA ticket as well covering the specific issue you are addressing.
94-
* Watch for upcoming articles on Spring by https://spring.io/blog[subscribing] to spring.io.
115+
* Before you log a bug, please search the
116+
https://jira.spring.io/browse/DATAKV[issue tracker] to see if someone has already reported the problem.
117+
* If the issue doesn’t already exist, https://jira.spring.io/browse/DATAKV[create a new issue].
118+
* Please provide as much information as possible with the issue report, we like to know the version of Spring Data that you are using and JVM version.
119+
* If you need to paste code, or include a stack trace use JIRA `{code}…{code}` escapes before and after your text.
120+
* If possible try to create a test-case or project that replicates the issue. Attach a link to your code or a compressed file containing your code.
95121

96-
Before we accept a non-trivial patch or pull request we will need you to https://cla.pivotal.io/sign/spring[sign the 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. If you forget to do so, you'll be reminded when you submit a pull request.
97-
Active contributors might be asked to join the core team, and given the ability to merge pull requests.
122+
== Building from Source
98123

99-
= Running CI tasks locally
124+
You don’t need to build from source to use Spring Data (binaries in https://repo.spring.io[repo.spring.io]), but if you want to try out the latest and greatest, Spring Data can be easily built with the https://github.com/takari/maven-wrapper[maven wrapper].
125+
You also need JDK 1.8.
100126

101-
Since this pipeline is purely Docker-based, it's easy to:
127+
[source,bash]
128+
----
129+
$ ./mvnw clean install
130+
----
131+
132+
If you want to build with the regular `mvn` command, you will need https://maven.apache.org/run-maven/index.html[Maven v3.5.0 or above].
102133

103-
* Debug what went wrong on your local machine.
104-
* Test out a a tweak to your `test.sh` script before sending it out.
105-
* Experiment against a new image before submitting your pull request.
134+
_Also see link:CONTRIBUTING.adoc[CONTRIBUTING.adoc] if you wish to submit pull requests, and in particular please sign the https://cla.pivotal.io/sign/spring[Contributor’s Agreement] before your first change, is trivial._
106135

107-
All of these use cases are great reasons to essentially run what the CI server does on your local machine.
136+
=== Building reference documentation
108137

109-
IMPORTANT: To do this you must have Docker installed on your machine.
138+
Building the documentation builds also the project without running tests.
110139

111-
1. `docker run -it --mount type=bind,source="$(pwd)",target=/spring-data-keyvalue-github adoptopenjdk/openjdk8:latest /bin/bash`
112-
+
113-
This will launch the Docker image and mount your source code at `spring-data-keyvalue-github`.
114-
+
115-
2. `cd spring-data-keyvalue-github`
116-
+
117-
Next, run your tests from inside the container:
118-
+
119-
3. `./mvnw clean dependency:list test -Dsort` (or whatever profile you need to test out)
140+
[source,bash]
141+
----
142+
$ ./mvnw clean install -Pdistribute
143+
----
120144

121-
Since the container is binding to your source, you can make edits from your IDE and continue to run build jobs.
145+
The generated documentation is available from `target/site/reference/html/index.html`.
122146

123-
If you test building the artifact, do this:
147+
== Examples
124148

125-
1. `docker run -it --mount type=bind,source="$(pwd)",target=/spring-data-keyvalue-github adoptopenjdk/openjdk8:latest /bin/bash`
126-
+
127-
This will launch the Docker image and mount your source code at `spring-data-keyvalue-github`.
128-
+
129-
2. `cd spring-data-keyvalue-github`
130-
+
131-
Next, try to package everything up from inside the container:
132-
+
133-
3. `./mvnw -Pci,snapshot -Dmaven.test.skip=true clean package`
149+
* https://github.com/spring-projects/spring-data-examples/[Spring Data Examples] contains example projects that explain specific features in more detail.
134150

135-
NOTE: Docker containers can eat up disk space fast! From time to time, run `docker system prune` to clean out old images.
151+
== License
136152

153+
Spring Data KeyValue is Open Source software released under the https://www.apache.org/licenses/LICENSE-2.0.html[Apache 2.0 license].

0 commit comments

Comments
 (0)