Skip to content

Commit 4e1179f

Browse files
author
Adrian Cole
committed
Adds HACKING file, to demystify change to Feign
1 parent 14402d8 commit 4e1179f

3 files changed

Lines changed: 74 additions & 11 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
11
# Contributing to Feign
2+
Please read [HACKING](./HACKING.md] prior to raising change.
23

34
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`).
45

56
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).
67

78
## License
89

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]
1011

1112
All files are released with the Apache 2.0 license.
1213

‎HACKING.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Hacking Feign
2+
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
62+
maintaining it, including Q&A support for years.

‎README.md‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -63,13 +63,13 @@ CloudDNS cloudDNS = feign.target(new CloudIdentityTarget<CloudDNS>(user, apiKey)
6363
```
6464

6565
### Examples
66-
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).
6767

6868
### Integrations
6969
Feign intends to work well within Netflix and other Open Source communities. Modules are welcome to integrate with your favorite projects!
7070

7171
### 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.
7373

7474
Add `GsonEncoder` and/or `GsonDecoder` to your `Feign.Builder` like so:
7575

@@ -82,7 +82,7 @@ GitHub github = Feign.builder()
8282
```
8383

8484
### 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.
8686

8787
Add `JacksonEncoder` and/or `JacksonDecoder` to your `Feign.Builder` like so:
8888

@@ -94,7 +94,7 @@ GitHub github = Feign.builder()
9494
```
9595

9696
### 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.
9898

9999
Here's an example of how to configure Sax response parsing:
100100
```java
@@ -106,7 +106,7 @@ api = Feign.builder()
106106
```
107107

108108
### 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.
110110

111111
Add `JAXBEncoder` and/or `JAXBDecoder` to your `Feign.Builder` like so:
112112

@@ -118,7 +118,7 @@ api = Feign.builder()
118118
```
119119

120120
### 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.
122122

123123
Here's the example above re-written to use JAX-RS:
124124
```java
@@ -133,7 +133,7 @@ GitHub github = Feign.builder()
133133
.target(GitHub.class, "https://api.github.com");
134134
```
135135
### OkHttp
136-
[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.
137137

138138
To use OkHttp with Feign, add the OkHttp module to your classpath. Then, configure Feign to use the OkHttpClient:
139139

@@ -144,7 +144,7 @@ GitHub github = Feign.builder()
144144
```
145145

146146
### Ribbon
147-
[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).
148148

149149
Integration requires you to pass your ribbon client name as the host part of the url, for example `myAppProd`.
150150
```java
@@ -153,7 +153,7 @@ MyService api = Feign.builder().client(RibbonClient.create()).target(MyService.c
153153
```
154154

155155
### 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).
157157

158158
To use Hystrix with Feign, add the Hystrix module to your classpath. Then use the `HystrixFeign` builder:
159159

@@ -163,7 +163,7 @@ MyService api = HystrixFeign.builder().target(MyService.class, "https://myAppPro
163163
```
164164

165165
### 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.)
167167

168168
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:
169169

0 commit comments

Comments
 (0)