CONTRIBUTING.md

Contributing to Salt

Rules

1. PR everything. Commits made directly to main are prohibited, except under specific circumstances
2. Use feature branches. Create an issue for every single feature or bug and tag it. If you are a core contributor, create a branch named feature/[issue #] to resolve the issue. If you are not, fork and branch.
3. Use github "Fixes #[issue]" syntax on your PRs to indicate which issues you are attempting to resolve
4. Keep salt-core small. If some piece of functionality can fit in a separate salt-* module, then it probably should
5. Code coverage is strictly enforced at 100%, so don't worry if your build fails prior to PRing
6. Please try to follow the Scala coding style exemplified by existing source files

Developing and Testing

Since testing Salt requires a Spark cluster, a containerized development/test environment is included via Docker. If you have docker installed, you can interactively build and test Salt within that environment:

$ ./test-environment

# then, attach to the container
$ docker ps
CONTAINER ID        IMAGE                      COMMAND             CREATED             STATUS              PORTS                                            NAMES
f5a2add1579a        uncharted/sparklet:2.0.0   "/init bash"        2 minutes ago       Up 2 minutes        0.0.0.0:8080->8080/tcp, 0.0.0.0:9999->9999/tcp   salt-core

$ docker attach f5a2add1579a

# then, inside the running container
$ ./gradlew

This will mount the code directory into the container as a volume, allowing you to make code changes on your host machine and test them on-the-fly.

You can also debug the test suite using remote debugging on port 9999. If you're on linux, the host for the debugger will be localhost. If you're on Windows or OSX, then it'll be the ip of your docker toolbox VM.

# start the test container as before
$ ./test-environment

# then, attach to the container
$ docker ps
CONTAINER ID        IMAGE                      COMMAND             CREATED             STATUS              PORTS                                            NAMES
f5a2add1579a        uncharted/sparklet:2.0.0   "/init bash"        2 minutes ago       Up 2 minutes        0.0.0.0:8080->8080/tcp, 0.0.0.0:9999->9999/tcp   salt-core

$ docker attach f5a2add1579a

# then, inside the running container
$ ./gradlew debug

# You'll see a message indicating when you should connect your debugger.

Deploying to Sonatype Central Repository

Staging and deployment to the Sonatype Central Repository is restricted to core contributors.

You will need the Salt signing key in your GPG keyring. Then, create a gradle.properties file in the root project directory (.gitignored for security reasons), which contains the following credentials:

signing.keyId=[Salt signing key ID]
signing.password=[Salt signing key password]
signing.secretKeyRingFile=[/path/to/your/.gnupg/secring.gpg]

ossrhUsername=[your-jira-id]
ossrhPassword=[your-jira-password]

Finally, deploy a Nexus-compatible set of artifacts:

$ ./gradlew uploadArchives

Release of the artifacts can be achieved here using the process outlined here