Skip to content

Latest commit

 

History

History
122 lines (87 loc) · 5.55 KB

CONTRIBUTING.md

File metadata and controls

122 lines (87 loc) · 5.55 KB
Raw

Contributing

If you want to contribute to the project, you can find some helpful information here.

How can I help?

Thanks for taking interest in helping us develop FS2!

We welcome all kinds of contribution, including but not limited to:

  • 📖 documentation improvements, explanatory images/diagrams, fixes in typos, useful links
  • 🧹 refactorings of messy code, build structure, increasing test coverage or quality
  • 🚀 new features and bugfixes (including bug reports and feature requests).

Writing documentation is valuable for learning, so if you find some explanation insufficient, overly complicated or incorrect, it's a perfect opportunity to make a change to it!

If at any point you run into problems, you can always ask a question on the fs2-dev Gitter channel.

How to submit a change

If you see something worth adding, make the relevant changes in a fork of the source code and submit a pull request to the project. If you don't know what you could help with, take a look at the issues marked as "help wanted" or ask on Gitter.

We follow similar rules to the cats-effect project's. Most importantly, any contributions are expected to be made in the form of GitHub pull requests to the FS2 repository. Usually it takes two approvals for a change to be merged. If it takes too long to get it approved, feel free to ask on the Gitter channel.

Remember to follow the code of conduct in online and offline discourse.

Building the project locally

Prerequisites

You'll need JDK 11, sbt, Node.JS (for running ScalaJS tests) and Jekyll (for building the microsite).

We use several sbt plugins to build and check the project, including MiMa (Migration Manager), scalafmt and sbt-microsites.

Build process

To compile the code for the whole repository, you can start an interactive sbt shell:

$ sbt
[info] Loading global plugins from /Users/contributor/.sbt/1.0/plugins
[info] Loading settings for project fs2-build from plugins.sbt,metals.sbt ...
[info] Loading project definition from /Users/contributor/dev/fs2/project
[info] Loading settings for project root from version.sbt,build.sbt ...
[info] Set current project to root (in build file:/Users/contributor/dev/fs2/)
sbt:root>

Inside the shell, you can compile the sources for the currently selected Scala version using the compile command. To compile the code for all Scala versions enabled in the build, use +compile. To include tests, test:compile or +test:compile, accordingly.

Testing

To test the code, you can run the test command in sbt. If you want the tests on a single plaform, you can use testJVM or testJS instead (these are defined as aliases in the build.sbt file).

It is possible to run a single test suite from a project on a single platform by executing a more specific task, like coreJVM/testOnly fs2.PullSpec.

You can list all available projects by executing the projects task:

sbt:root> projects
[info] In file:/Users/kubukoz/IdeaProjects/fs2/
[info] 	   benchmark
[info] 	   coreJS
[info] 	   coreJVM
[info] 	   docs
[info] 	   experimental
[info] 	   io
[info] 	   microsite
[info] 	   reactiveStreams
[info] 	 * root

Before submitting a change for review, it's worth running some extra checks that will be triggered in Continuous Integration:

sbt:root> fmtCheck; test; doc; mimaReportBinaryIssues; docs/mdoc; microsite/makeMicrosite

That will check the formatting, run all tests on the supported platforms, report any binary compatibility issues (as detected by MiMa) and build the site.

If you run into any problems with tests, binary compatibility or other issues, feel free to ask questions on the Gitter channel.

Website

To build the microsite, use the microsite/makeMicrosite task in sbt. Then, go to site/target/site, and run a HTTP server on the port of your choice:

sbt:root> microsite/makeMicrosite
info: Compiled in 24s (0 errors, 0 warnings)
[info] Configuration file: /Users/contributor/dev/fs2/site/target/scala-2.13/resource_managed/main/jekyll/_config.yml
[info]             Source: /Users/contributor/dev/fs2/site/target/scala-2.13/resource_managed/main/jekyll
[info]        Destination: /Users/contributor/dev/fs2/site/target/jekyll
[info]  Incremental build: disabled. Enable with --incremental
[info]       Generating...
[info]                     done in 0.592 seconds.
[info]  Auto-regeneration: disabled. Use --watch to enable.
[success] Total time: 29 s, completed Jan 24, 2020, 2:36:31 PM
sbt:root> exit
[info] shutting down sbt server

$ cd site/target/site
$ python -m SimpleHTTPServer 4000 . # Any other server would do
Serving HTTP on 0.0.0.0 port 4000 ...