You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 4e1179f
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: CONTRIBUTING.md
+2-1Lines changed: 2 additions & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,12 +1,13 @@
1
1
# Contributing to Feign
2
+
Please read [HACKING](./HACKING.md] prior to raising change.
2
3
3
4
If you would like to contribute code you can do so through GitHub by forking the repository and sending a pull request (on a branch other than `master` or `gh-pages`).
4
5
5
6
When submitting code, please ensure you follow the [Google Style Guide](http://google-styleguide.googlecode.com/svn/trunk/javaguide.html). For example, you can format code with IntelliJ 13 using [this file](https://google.github.io/styleguide/intellij-java-google-style.xml) and with IntelliJ 15 using [this file](https://raw.githubusercontent.com/garukun/styleguide/add-intellij-15-java/intellij-15-java-google-style.xml).
6
7
7
8
## License
8
9
9
-
By contributing your code, you agree to license your contribution under the terms of the APLv2: https://github.com/Netflix/Feign/blob/master/LICENSE
10
+
By contributing your code, you agree to license your contribution under the terms of the [APLv2](./LICENSE]
10
11
11
12
All files are released with the Apache 2.0 license.
Feign is optimized for maintenance vs flexibility. It prefers small
3
+
features that have been asked for repeated times, that are insured with
4
+
tests, and have clear use cases. This limits the lines of code and count
5
+
of modules in Feign's repo.
6
+
7
+
Code design is opinionated including below:
8
+
9
+
* Classes and methods default to package, not public visibility.
10
+
* Changing certain implementation classes may be unsupported.
11
+
* 3rd-party dependencies, and gnarly apis like java.beans are avoided.
12
+
13
+
## How to request change
14
+
The best way to approach something not yet supported is to ask on
15
+
[gitter](https://gitter.im/Netflix/feign) or [raise an issue](https://github.com/Netflix/feign/issues).
16
+
Asking for the feature you need (like how to deal with command groups)
17
+
vs a specific implementation (like making a private type public) will
18
+
give you more options to accomplish your goal.
19
+
20
+
Advice usually comes in two parts: advice and workaround. Advice may be
21
+
to change Feign's code, or to fork until the feature is more widely
22
+
requested.
23
+
24
+
## How change works
25
+
High quality pull requests that have clear scope and tests that reflect
26
+
the intent of the feature are often merged and released in days. If a
27
+
merged change isn't immediately released and it is of priority to you,
28
+
nag (make a comment) on your merged pull request until it is released.
29
+
30
+
## How to experiment
31
+
Changes to Feign's code are best addressed by the feature requestor in a
32
+
pull request *after* discussing in an issue or on gitter. By discussing
33
+
first, there's less chance of a mutually disappointing experience where
34
+
a pull request is rejected. Moreover, the feature may be already present!
35
+
36
+
Albeit rare, some features will be deferred or rejected for inclusion in
37
+
Feign's main repository. In these cases, the choices are typically to
38
+
either fork the repository, or make your own repository containing the
39
+
change.
40
+
41
+
### Forks are welcome!
42
+
Forking isn't bad. It is a natural place to experiment and vet a feature
43
+
before it ends up in Feign's main repository. Large features or those
44
+
which haven't satisfied diverse need are often deferred to forks or
45
+
separate repositories (see [Rule of Three](http://blog.codinghorror.com/rule-of-three/)).
46
+
47
+
### Large integrations -> separate repositories
48
+
If you look carefully, you'll notice Feign integrations are often less
49
+
than 1000 lines of code including tests. Some features are rejected for
50
+
inclusion solely due to the amount of maintenance. For example, adding
51
+
some features might imply tying up maintainers for several days or weeks
52
+
and resulting in a large percentage increase in the size of feign.
53
+
54
+
Large integrations aren't bad, but to be sustainable, they need to be
55
+
isolated where the maintenance of that feature doesn't endanger the
56
+
maintainability of Feign itself. Feign has been going since 2012, without
57
+
the need of full-time attention. This is largely because maintenance is
58
+
low and approachable.
59
+
60
+
A good example of a large integration is [spring-cloud-netflix](https://github.com/spring-cloud/spring-cloud-netflix/tree/master/spring-cloud-netflix-core/src/main/java/org/springframework/cloud/netflix/feign).
61
+
Spring Cloud Netflix is sustainable as it has had several people
Feign includes example [GitHub](https://github.com/Netflix/feign/tree/master/example-github) and [Wikipedia](https://github.com/Netflix/feign/tree/master/example-wikipedia) clients. The denominator project can also be scraped for Feign in practice. Particularly, look at its [example daemon](https://github.com/Netflix/denominator/tree/master/example-daemon).
66
+
Feign includes example [GitHub](./example-github) and [Wikipedia](./example-wikipedia) clients. The denominator project can also be scraped for Feign in practice. Particularly, look at its [example daemon](https://github.com/Netflix/denominator/tree/master/example-daemon).
67
67
68
68
### Integrations
69
69
Feign intends to work well within Netflix and other Open Source communities. Modules are welcome to integrate with your favorite projects!
70
70
71
71
### Gson
72
-
[Gson](https://github.com/Netflix/feign/tree/master/gson) includes an encoder and decoder you can use with a JSON API.
72
+
[Gson](./gson) includes an encoder and decoder you can use with a JSON API.
73
73
74
74
Add `GsonEncoder` and/or `GsonDecoder` to your `Feign.Builder` like so:
75
75
@@ -82,7 +82,7 @@ GitHub github = Feign.builder()
82
82
```
83
83
84
84
### Jackson
85
-
[Jackson](https://github.com/Netflix/feign/tree/master/jackson) includes an encoder and decoder you can use with a JSON API.
85
+
[Jackson](./jackson) includes an encoder and decoder you can use with a JSON API.
86
86
87
87
Add `JacksonEncoder` and/or `JacksonDecoder` to your `Feign.Builder` like so:
88
88
@@ -94,7 +94,7 @@ GitHub github = Feign.builder()
94
94
```
95
95
96
96
### Sax
97
-
[SaxDecoder](https://github.com/Netflix/feign/tree/master/sax) allows you to decode XML in a way that is compatible with normal JVM and also Android environments.
97
+
[SaxDecoder](./sax) allows you to decode XML in a way that is compatible with normal JVM and also Android environments.
98
98
99
99
Here's an example of how to configure Sax response parsing:
100
100
```java
@@ -106,7 +106,7 @@ api = Feign.builder()
106
106
```
107
107
108
108
### JAXB
109
-
[JAXB](https://github.com/Netflix/feign/tree/master/jaxb) includes an encoder and decoder you can use with an XML API.
109
+
[JAXB](./jaxb) includes an encoder and decoder you can use with an XML API.
110
110
111
111
Add `JAXBEncoder` and/or `JAXBDecoder` to your `Feign.Builder` like so:
112
112
@@ -118,7 +118,7 @@ api = Feign.builder()
118
118
```
119
119
120
120
### JAX-RS
121
-
[JAXRSContract](https://github.com/Netflix/feign/tree/master/jaxrs) overrides annotation processing to instead use standard ones supplied by the JAX-RS specification. This is currently targeted at the 1.1 spec.
121
+
[JAXRSContract](./jaxrs) overrides annotation processing to instead use standard ones supplied by the JAX-RS specification. This is currently targeted at the 1.1 spec.
122
122
123
123
Here's the example above re-written to use JAX-RS:
[OkHttpClient](https://github.com/Netflix/feign/tree/master/okhttp) directs Feign's http requests to [OkHttp](http://square.github.io/okhttp/), which enables SPDY and better network control.
136
+
[OkHttpClient](./okhttp) directs Feign's http requests to [OkHttp](http://square.github.io/okhttp/), which enables SPDY and better network control.
137
137
138
138
To use OkHttp with Feign, add the OkHttp module to your classpath. Then, configure Feign to use the OkHttpClient:
[RibbonClient](https://github.com/Netflix/feign/tree/master/ribbon) overrides URL resolution of Feign's client, adding smart routing and resiliency capabilities provided by [Ribbon](https://github.com/Netflix/ribbon).
147
+
[RibbonClient](./ribbon) overrides URL resolution of Feign's client, adding smart routing and resiliency capabilities provided by [Ribbon](https://github.com/Netflix/ribbon).
148
148
149
149
Integration requires you to pass your ribbon client name as the host part of the url, for example `myAppProd`.
150
150
```java
@@ -153,7 +153,7 @@ MyService api = Feign.builder().client(RibbonClient.create()).target(MyService.c
153
153
```
154
154
155
155
### Hystrix
156
-
[HystrixFeign](https://github.com/Netflix/feign/tree/master/hystrix) configures circuit breaker support provided by [Hystrix](https://github.com/Netflix/Hystrix).
156
+
[HystrixFeign](./hystrix) configures circuit breaker support provided by [Hystrix](https://github.com/Netflix/Hystrix).
157
157
158
158
To use Hystrix with Feign, add the Hystrix module to your classpath. Then use the `HystrixFeign` builder:
159
159
@@ -163,7 +163,7 @@ MyService api = HystrixFeign.builder().target(MyService.class, "https://myAppPro
163
163
```
164
164
165
165
### SLF4J
166
-
[SLF4JModule](https://github.com/Netflix/feign/tree/master/slf4j) allows directing Feign's logging to [SLF4J](http://www.slf4j.org/), allowing you to easily use a logging backend of your choice (Logback, Log4J, etc.)
166
+
[SLF4JModule](./slf4j) allows directing Feign's logging to [SLF4J](http://www.slf4j.org/), allowing you to easily use a logging backend of your choice (Logback, Log4J, etc.)
167
167
168
168
To use SLF4J with Feign, add both the SLF4J module and an SLF4J binding of your choice to your classpath. Then, configure Feign to use the Slf4jLogger:
0 commit comments