1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
= Developer Guide
:toclevels: 5
:toc:
== Audience
You want contribute to, or learn about, the development of the Pomegranate library.
== Contributing
We very much appreciate contributions from the community.
=== Issue First Please
If you have an idea or a fix, please do raise a GitHub issue before investing in any coding effort.
That way we can discuss first.
Writing code is the easy part, maintaining it forever is the hard part.
That said, if you notice a simple typo, a PR without an issue is fine.
=== Submitting a Pull Request
Please never force push on your PR, as this makes reviewing incremental changes impossible for us.
When we merge your PR, we'll usually squash it, so that will clean up any rambling work in progress.
== Environmental Overview
=== Developer Prerequisites
The current version of Babashka.
The current version of Clojure.
JDK8+
=== Foundational Library
Leiningen and other tools rely on Pomegranate behaving the way it does.
We must be very careful when making changes.
== Docs
All documentation is written in AsciiDoc.
@lread likes to follow https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line[AsciiDoc best practice of one sentence per line] but won't be entirely pedantic about that.
We host our docs on cljdoc.
== The Public API
When making changes to Pomegranate, understand that currently any public method is considered part of the public API.
We must be careful not to expose what we feel are implementation details.
== Babashka Tasks
We use Babashka tasks, to see all available tasks run:
[source,shell]
----
bb tasks
----
Optionally:
[source,shell]
----
$ bb clean
$ bb download-deps
----
=== Testing
Run Clojure tests.
We have 2 suites:
* `:unit` - general unit tests
* `:isolated` - tests that pollute classloaders and classpath, and are therefore run separately
To run all test suites under Clojure `1.4` (our minimum supported version):
[source,shell]
----
$ bb test
----
To only run a single suite:
[source,shell]
----
$ bb test --suite :unit
----
You can also include Cognitect test runner options:
[source,shell]
----
$ bb test --suite :unit --var cemerick.pomegranate.aether-test/live-resolution
----
...and/or Clojure version:
[source,shell]
----
$ bb test --clj-version 1.9
----
(specify `:all` to test against all supported Clojure versions)
=== Linting
Our CI workflow lints sources with clj-kondo, and eastwood - and you can too!
[source,shell]
----
$ bb lint-kondo
$ bb lint-eastwood
----
To run both: `bb lint`
=== Vulnerability scanning
We automatically scan for vulnerabilities in our dependencies on CI.
If you want to run this work locally, you can for example:
[source,shell]
----
$ NVD_API_TOKEN=your-token-here bb nvd-scan
----
Replace `your-token-here` with your personal nvd api token which you can easily request from https://nvd.nist.gov/developers/request-an-api-key.
=== Outdated Deps
You can check for outdated dependencies via:
[source,shell]
----
$ bb outdated
----
Before upgrading `+org.apache.maven.*+` deps, make sure there is a good reason to do so.
Otherwise, don't bother bumping these deps.
Good reasons to bump `+org.apache.maven.*+` deps might be:
* to overcome a security vulnerability
* there is some necessary new/corrected behaviour
|
