Skip to content

Latest commit

 

History

History
93 lines (60 loc) · 4.17 KB

CONTRIBUTING.md

File metadata and controls

93 lines (60 loc) · 4.17 KB
Raw

Contributors Guide

👍🎉 Thank YOU for taking the time to contribute to Surge! 🎉👍

Here are some ways you can help:

Did you find a bug or want to make a feature request?

  • Ensure the bug or feature was not already reported by searching on GitHub under Issues.

  • If you're unable to find an open issue addressing the problem, either: open a new bug or submit a feature request. We have created a template which walks you through all the details needed to help address the bug/request in a timely manner.

Did you fix a bug or want to submit a new feature?

  • Fork the Surge repository on GitHub. You may push any feature branches to your own fork and open pull requests against the main repository from there.

  • Follow the Code Conventions below as you make your fix.

  • Once you have compiled your fix/additions, Open a new pull request.

Developing Locally

We use sbt for building Surge. The sbt docs are a great way to learn the basics about sbt if you aren't already familiar with the tool.

To compile all of the Surge modules:

sbt compile

To run all of the tests:

sbt test

If you want to publish the Surge artifacts to your local Ivy repository to test your changes in another project:

sbt publishLocal

Code Conventions

Coding Guidelines

  • Keep the code DRY as much as possible.
  • Leave the code better than you found it.
  • Avoid the use of @author tags since it does not encourage Collective Code Ownership.

Testing Guidelines

  • When fixing a bug, add a unit test that reproduces the original error along with the fix.
  • Prefer smaller, more focused unit tests over larger sweeping integration tests where possible.
  • New features should have comprehensive testing.

Pull Request Guidelines

Pull request titles are used in the release notes and should be a descriptive sentence of what the Pull Request is doing and include a Github Issue number if applicable. It should be possible to understand what your change does, but not necessarily how it's accomplished from this single sentence. In the description for your pull request, include any additional details to describe how your solution works.

Documentation

Our documentation & examples can be found in the surge-docs module. We leverage sbt Paradox to pull examples for the docs from real code.

If you'd like to preview the docs site:

sbt surge-docs/previewSite

Binary Compatibility

Surge tries to guarantee binary compatibility within a minor version. We use MiMa to validate the binary compatibility of incoming pull requests. If your pull request fails binary compatibility checks, check with a member of the core team on whether the breaking change can be safely ignored or if it would break binary compatibility. To ignore, add the exclude statements generated by MiMa to a file named <module>/src/main/mima-filters/<last-version>.backwards.excludes.

It is ok to ignore binary compatibility for:

  • Anything intended to be internal - i.e. in a package with a name including internal

You can check binary compatibility locally using:

sbt mimaReportBinaryIssues

Navigating the Code

Branches

Depending on which version of Surge you want to modify, you may need to base your work off of a particular branch:

  • main - active development branch for Surge 0.5.x

Tags

  • good first issue - Indicates an issue that's good for someone new to the repository. These issues are isolated to smaller sections of the code and don't require in-depth knowledge of the full codebase in order to complete.