Skip to content

Commit 865eb1a

Browse files
xvikxvik
committed
update doc
1 parent 7cda910 commit 865eb1a

File tree

1 file changed

+66
-118
lines changed

1 file changed

+66
-118
lines changed

‎README.md‎

Lines changed: 66 additions & 118 deletions
Original file line numberDiff line numberDiff line change
@@ -8,16 +8,16 @@
88

99
### About
1010

11-
The main goal is to simplify new [github](https://github.com) java library setup.
11+
Generates java library project (or multi-module library), hosted on github with maven central publication.
12+
Ideal for new OSS project quick start.
1213

1314
Features:
1415
* Single and multi-module projects generation
1516
* [MIT](http://opensource.org/licenses/MIT) license (hardcoded)
1617
* [Gradle](http://www.gradle.org/) build (with support of optional and provided dependencies)
1718
* [Maven central](http://search.maven.org/) compatible artifacts (jar, sources, javadocs)
1819
* Ready for [spock](http://spockframework.org) tests ([documentation](http://docs.spockframework.org))
19-
* [Bintray](https://bintray.com/) publication (+ jars signing and maven central publishing)
20-
* CI: [travis](https://travis-ci.org/) (linux), [appveyor](https://www.appveyor.com/) (windows)
20+
* CI: [travis](https://travis-ci.com/) (linux), [appveyor](https://www.appveyor.com/) (windows)
2121
* Coverage with jacoco, merged from both win and linux builds in [codecov.io](https://codecov.io/)
2222
* Target jdk compatibility check with [animal sniffer](http://mojo.codehaus.org/animal-sniffer/) (you may use newer jdk to build, and keep compatibility with older jdk)
2323
* Code quality checks ([checkstyle](http://checkstyle.sourceforge.net/), [pmd](http://pmd.sourceforge.net/), [findbugs](http://findbugs.sourceforge.net/))
@@ -64,36 +64,76 @@ $ npm install -g generator-lib-java
6464

6565
You will need [github](https://github.com) user. Create it if you don't have already.
6666

67-
### Bintray setup
67+
### Maven central setup
6868

69-
Bintray automates files signing and maven central publishing.
70-
Project already generates valid artifacts for maven central, you just need to configure bintray.
69+
For maven central publication you must first register in sonatype and approve your group.
70+
Read this a bit [outdated article](https://medium.com/@vyarus/the-hard-way-to-maven-central-c9e16d163acc)
71+
for getting started.
7172

72-
Sign up [bintray](https://bintray.com/) and create maven repository to upload artifacts to (it's name is one of generator questions).
73+
For certificate generation see [java-lib plugin docs](https://github.com/xvik/gradle-java-lib-plugin#signing)
74+
Note that signing configuration required only for release (otherwise its ignored)
7375

74-
[Follow instruction](https://medium.com/@vyarus/the-hard-way-to-maven-central-c9e16d163acc)
75-
76-
Add bintray user and key to `~/.gradle/gradle.properties`
76+
After all you'll need to put the following properties into `~/.gradle/gradle.properties`
7777

7878
```
79-
bintrayUser=username
80-
bintrayKey=secretkey
79+
sonatypeUser =
80+
sonatypePassword =
81+
82+
signing.keyId = 78065050
83+
signing.password =
84+
signing.secretKeyRingFile = /path/to/certs.gpg
8185
```
8286

83-
If you will use automatic signing and certificate requires passphrase:
87+
Generator will check and warn you if something is not configured.
8488

85-
```
86-
gpgPassphrase=passphrase
87-
```
89+
### Publishing library to local repository only
90+
91+
If library is assumed to be used as internal library with local (corporate) maven repo,
92+
manual modifications required.
93+
94+
Remove `io.github.gradle-nexus.publish-plugin`.
95+
96+
Remove `ru.vyarus.github-info` (I assume your source would not be in github). And remove related
97+
`github` configuration block.
8898

89-
If you will use automatic maven central publishing add:
99+
Remove `signing` plugin if you don't need to sign artifacts for your repository.
90100

101+
Configure repository:
102+
103+
```groovy
104+
publishing {
105+
repositories {
106+
maven {
107+
url project.version.contains("SNAPSHOT")
108+
? "https://my-private-nexus.com/nexus/content/repositories/my-snapshots"
109+
: "https://my-private-nexus.com/nexus/content/repositories/my-releases"
110+
credentials {
111+
username = project.findProperty('myRepoUser')
112+
password = project.findProperty('myRepoPass')
113+
}
114+
}
115+
}
116+
}
91117
```
92-
sonatypeUser=username
93-
sonatypePassword=password
118+
119+
Change releasing task:
120+
121+
```groovy
122+
afterReleaseBuild {
123+
dependsOn = [publish]
94124
```
95125

96-
Generator will check and warn you if something is not configured.
126+
Now simple `publish` task deploys snapshot version and `release` task would perform complete release
127+
(with version change and tagging git).
128+
129+
To use published library declare custom repository in target project:
130+
131+
```groovy
132+
repositories {
133+
// usually root repo combining releases and snapshots
134+
maven { url 'https://my-private-nexus.com/nexus/content/groups/my/' }
135+
}
136+
```
97137

98138
### Usage
99139

@@ -114,10 +154,6 @@ Generator calls github to validate user correctness and suggest your name and em
114154
$ yo lib-java --offline
115155
```
116156

117-
NOTE: even if you chose syncing with maven central, build.gradle will contain false on initial generation, because
118-
it's impossible to use it on first release (package needs to be added to jcenter). See release section for more details.
119-
Anyway, your answer will be stored and on update (next generation) correct value will be set to config.
120-
121157
Project setup ready, start coding!
122158

123159
#### Build upgrade
@@ -145,27 +181,20 @@ Create [github](https://github.com) repo matching your library name and push pro
145181
In github project settings go to `Webhooks & services` and add `travis-ci` service.
146182

147183
Enable repository on services:
148-
* [travis](https://travis-ci.org/)
184+
* [travis](https://travis-ci.com/)
149185
* [appveyor](https://www.appveyor.com/)
150186

151187
And after next commit windows and linux builds will be performed automatically and combined coverage report
152188
will be available on [codecov](https://codecov.io/) (badges for all services are already generated in readme).
153189

154-
Bintray and maven central badges are generated in readme, but commented (uncomment before release).
190+
Maven central badge is generated in readme.
155191

156192
### Snapshots
157193

158194
[JitPack](https://jitpack.io) is ideal for snapshots: it builds github project and serves dependency for you.
159195
Special section in project readme is generated to show how to use it for snapshots.
160196
JitPack doesn't require any configuration to support your library.
161197

162-
Bintray is still used for releases, because:
163-
* Maven central require jar signing, which grants secure usage of your artifact (and prevents artifact changes,
164-
for example, malicious injections)
165-
* Bintray jcenter now become standard for java projects (second to maven central). It is trusted and, for example, in gradle enabled by default
166-
(no need to specify custom repository).
167-
* It's not used frequently, but bintray supports user notifications about new versions.
168-
169198
### Gitter
170199

171200
[Gitter](https://gitter.im) is a chat room for your repository. Most likely, with it you
@@ -201,7 +230,7 @@ $ gradlew dependencies
201230
Prints dependencies tree into console
202231

203232
```bash
204-
$ gradlew showDependenciesTree
233+
$ gradlew openDependencyReport
205234
```
206235

207236
Generates dependencies html report and launch it in default browser.
@@ -222,8 +251,6 @@ Releases library. Read release process section below before performing first rel
222251

223252
### Project details
224253

225-
[Sample build file](https://github.com/xvik/generator-lib-java/wiki/Build-file-annotated) with comments.
226-
227254
Used gradle plugins:
228255
* [java](http://www.gradle.org/docs/current/userguide/java_plugin.html)
229256
* [groovy](http://www.gradle.org/docs/current/userguide/groovy_plugin.html) to support spock tests
@@ -232,16 +259,14 @@ Used gradle plugins:
232259
* [jacoco](http://www.gradle.org/docs/current/userguide/jacoco_plugin.html) to build coverage report for coveralls
233260
* [pmd](http://www.gradle.org/docs/current/userguide/pmd_plugin.html) to check code quality with [PMD](http://pmd.sourceforge.net/) tool
234261
* [checkstyle](http://www.gradle.org/docs/current/userguide/checkstyle_plugin.html) to check code style rules with [checkstyle](http://checkstyle.sourceforge.net/index.html)
235-
* [findbugs](http://www.gradle.org/docs/current/userguide/findbugs_plugin.html) to find potential bugs with [findbugs](http://findbugs.sourceforge.net/)
236-
* [com.jfrog.bintray](https://github.com/bintray/gradle-bintray-plugin) for bintray publishing
262+
* [spotbugs](https://github.com/spotbugs/spotbugs-gradle-plugin) to find potential bugs with [spotbugs](https://spotbugs.github.io/)
263+
* [o.github.gradle-nexus.publish-plugin](https://github.com/gradle-nexus/publish-plugin) to simplify maven central publication
237264
* [com.github.ben-manes.versions](https://github.com/ben-manes/gradle-versions-plugin) to check dependencies versions updates
238265
* [net.researchgate.release](https://github.com/researchgate/gradle-release) for release (see [article](http://www.sosaywecode.com/gradle-release-plugin/) for additional plugin details)
239266
* [ru.vyarus.pom](https://github.com/xvik/gradle-pom-plugin) for simpler pom generation
240267
* [ru.vyarus.java-lib](https://github.com/xvik/gradle-java-lib-plugin) to prepare java artifacts setup
241268
* [ru.vyarus.github-info](https://github.com/xvik/gradle-github-info-plugin) to fill in github specific data
242269
* [ru.vyarus.quality](https://github.com/xvik/gradle-quality-plugin) to configure quality plugins and provide advanced reporting
243-
* [ru.vyarus.animalsniffer](https://github.com/xvik/gradle-animalsniffer-plugin) to verify jdk backwards compatibility when building on newer jdk
244-
* [io.spring.dependency-management](https://github.com/xvik/gradle-animalsniffer-plugin) to use maven BOMs (plugin used instead of gradle native BOM's support as more correct)
245270

246271
#### Optional dependencies
247272

@@ -259,7 +284,7 @@ or
259284
optional 'com.github.spotbugs:spotbugs-annotations:3.1.2'
260285
```
261286

262-
In generated pom these dependencies will be defined as provided or optional, but for gradle build it's
287+
In the generated pom these dependencies will be defined as provided or optional, but for gradle build it's
263288
the same as declaring them in `implementation` scope.
264289

265290
jsr305 provided dependency is defined by default in generated project (useful to guide firebug).
@@ -268,21 +293,6 @@ Scala note: The Scala compiler, unlike the Java compiler, [requires that annotat
268293
compiling against that library](https://issues.scala-lang.org/browse/SI-5420).
269294
If your library users will compile with Scala, they must declare a dependency on JSR-305 jar.
270295

271-
#### Java compatibility
272-
273-
It still makes sense to keep library compatibility with older java version (6 or 7), even when newer java used for development.
274-
275-
But when project compiled with newer jdk, there is a chance to use newer api, not available in target (older) jdk.
276-
[ru.vyarus.animalsniffer plugin](https://github.com/xvik/gradle-animalsniffer-plugin) checks jdk api usage.
277-
278-
There is special dependency configuration `signature` which defines target signature to check, e.g.:
279-
280-
```groovy
281-
signature 'org.codehaus.mojo.signature:java16-sun:+@signature'
282-
```
283-
284-
When no signatures defined, no check will be performed.
285-
286296
### Quality tools
287297

288298
Quality tools are configured by [ru.vyarus.quality plugin](https://github.com/xvik/gradle-quality-plugin).
@@ -312,20 +322,6 @@ $ gradlew install
312322

313323
And validate generated pom file and jars (in local maven repository ~/.m2/repository/..).
314324

315-
NOTE: Release plugin requires access to git repository without credentials, so it's
316-
better to allow storing credentials when using git console.
317-
Windows users with sysgit 1.8.1 and up could use:
318-
319-
```bash
320-
$ git config --global credential.helper wincred
321-
```
322-
323-
To [avoid problems](https://github.com/townsfolk/gradle-release/issues/81).
324-
325-
Bintray and maven central badges are commented in readme - uncomment them (remove maven badge if not going to publish there)
326-
327-
Automatic maven central publication is impossible on first release, because package is not yet in jcentral (we will enable it after).
328-
329325
#### General release process
330326

331327
Update `CHANGELOG.md`.
@@ -346,54 +342,6 @@ During release, plugin will create tag (new github release appear) and update ve
346342
You may want to create github release: release will only create tag. To create release go to github releases, click on tag and press 'edit'.
347343
I usually use text from changelog as release message, but you may expand it with other release specific notes.
348344

349-
#### After first release
350-
351-
Github repository name and changelog file will be [automatically configured](https://github.com/xvik/gradle-github-info-plugin#comjfrogbintray)
352-
for bintray plugin. If you renamed changelog file from CHANGELOG.md then you will have to [specify it's name](https://github.com/xvik/gradle-github-info-plugin#available-properties)
353-
(or configure it manually on bintray package edit page).
354-
Go to your bintray package page, click on 'readme' tab and select 'github page'.
355-
Do the same on 'release notes' tab (to show CHANGELOG.md file).
356-
357-
After actual release press 'add to jcenter' button to request jcenter linking (required for maven central publication
358-
and even if you don't want to sync to maven central, linking to jcenter will simplify library usage for end users).
359-
360-
After acceptance in jcenter (approve takes less than 1 day) do manual maven central synchronization in bintray ui.
361-
362-
Now automatic maven central publication could be enabled in project config `build.gradle`:
363-
364-
```
365-
bintray {
366-
...
367-
mavenCentralSync {
368-
sync = true
369-
```
370-
371-
Note that maven publication requires files signing option active too (if you not choose it during project generation):
372-
373-
```
374-
gpg {
375-
sign = true
376-
```
377-
378-
All future releases will publish to maven central automatically.
379-
380-
#### If release failed
381-
382-
Nothing bad could happen.
383-
384-
If bintray upload failed, you can always upload one more time.
385-
If you uploaded bad version and want to re-release it, simply remove version files on bintray package version page and re-do release.
386-
387-
If release failed, but plugin already commit new version - you can release again from this state (no need to revert).
388-
389-
Release plugin changes only version in `gradle.properties` and creates git tag.
390-
Version could be reverted manually (by correcting file) and git tag could be also removed like this:
391-
392-
```bash
393-
git tag -d release01
394-
git push origin :refs/tags/release01
395-
```
396-
397345
### Support
398346

399347
[Gitter chat room](https://gitter.im/xvik/generator-lib-java)

0 commit comments

Comments
 (0)