Arrow is an inclusive community powered by awesome individuals like you. As an actively growing ecosystem, Arrow and its associated libraries and toolsets are in need of new contributors! We have issues suited for all levels, from entry to advanced, and our maintainers are happy to provide 1:1 mentoring. All are welcome in Arrow.
If you’re looking to contribute, have questions, or want to keep up-to-date about what’s happening, please follow us here and say hello!
In this page you'll find these guidelines for contributions:
- How to build the libraries
- How to generate and validate the documentation
- How to run the website in your local workspace
- How to propose an improvement
- Notes
Can't find what you're looking for? Please, contact us at #arrow on Kotlin Slack or create an issue.
- JDK 8
To build all the libraries (compilation + tests) and examples:
cd arrow-libs
./gradlew buildTo build just CORE libraries, FX libraries, OPTICS libraries, etc. select the correspondent directory.
For instance, for CORE libraries:
cd arrow-libs/core
./gradlew buildDokka is responsible for generating documentation based on source code annotations. Ank is in charge of compiling and validating your doc snippets and deploying the proper binaries for those.
In order to generate the documentation and validate it:
cd arrow-libs
./gradlew buildDocThat Gradle task is equivalent to run Dokka and Ank:
cd arrow-libs
./gradlew dokka
cd ../arrow-site
./gradlew runAnkWhenever you are documenting a new type (type class, data type, whatever) you'll wonder how to add code snippets to it. Please, use the following priority check list:
If the snippet is just docs for a public method of a type (as in arguments, return type, or how it should be used from call sites), that should be inlined in the Kdocs of that given method using Dokka. That's done under the actual type file. Here you have a simple example for Option methods.
That will automatically inline the docs of each method into the docs of the given data type. This is intended to be used just for public APIs exposed to users of the library.
If your snippet is showing examples on how to use the public APIs in a broader scenario (like describing FP patterns or similar), then you'll add those snippets to the described docs Markdown file.
For the mentioned cases, you should double-check which Ank modifiers you want to use for the snippets (silent, replace, or outFile(<file>)). You'll find more details about each one of those in Ank docs. See some real examples on this docs PR.
Also note that you can make your Ank snippets editable and runnable in the actual browser, which is quite handy. Just add this {: data-executable='true'} before your Ank Kotlin snippet. That must be used as a norm for all the snippets except for the ones that just represent infrastructure for following snippets (where there's not much value on making them runnable).
cd arrow-site
./gradlew buildSiteThat Gradle task is equivalent to run Dokka, Ank and Jekyll build:
cd arrow-libs
./gradlew dokka
cd ../arrow-site
./gradlew runAnk
bundle install --gemfile Gemfile --path vendor/bundle
bundle exec jekyll serve -s build/siteThis will install any needed dependencies locally, and will use it to launch the complete website in 127.0.0.1:4000 so you can open it with a standard browser.
If you get an error while installing the Ruby gem http_parser, check if the path to your Arrow directory contains spaces. According to this issue, the installation with spaces in the path is currently not working.
Test for broken links in documentation using
wget --spider -r -nd -nv -l 5 http://127.0.0.1:4000If it's the first time you contribute with a GitHub repository, take a look at Collaborating with issues and pull requests.
Please, follow the link to create an issue.
If you want to propose a fix, rename, move, etc. please, ensure that these checks pass:
- Required checks:
arrow libraries: buildarrow libraries: build documentation
- The approval by 2 maintainers of the Arrow Community.
Please, ensure these points when adding a new feature:
- Include documentation via Dokka. Please, find examples in the existing code to follow the same pattern.
- Use Ank to validate for code snippets
- Include tests that cover the proper cases
When creating the pull request, ensure that these checks pass:
- Required automatic checks:
arrow libraries: buildarrow libraries: build documentation
- The approval by 2 maintainers of the Arrow Community.
Both successful or failed build checks allow to download the tests report to review it:
When merging the pull request, a new SNAPSHOT library will be published into Sonatype OSSRH.
On the other hand, the documentation for the next version (SNAPSHOT) will be updated:
If any of these actions fails, an issue will be created to be solved as soon as possible.
The use of Gradle appears in several places: arrow-libs, arrow-libs/core, arrow-stack, etc.
However, links are being used so it's just necessary to upgrade Gradle in arrow-libs directory:
cd arrow-libs
./gradlew wrapper --gradle-version <new-version>
This short guideline provides all the things to keep in mind when adding a new module:
- Configuration:
- Add
<module>/gradle.properties - Add
<module>/build.gradle - Update
settings.xml
- Add
- Website:
- Update sidebar files
- Utilities:
- Update BOM file: build.gradle
| Configuration | Use | Note |
|---|---|---|
api |
compilation | exported to consumers for compilation |
implementation |
compilation + runtime | exported to consumers for runtime |
compileOnly |
just compilation | not exported to consumers |
runtimeOnly |
just runtime | exported to consumers for runtime |
testImplementation |
test compilation + test runtime | |
testCompileOnly |
test compilation | |
testRuntimeOnly |
test runtime |