CONTRIBUTING.adoc

Pkl Contributor’s Guide

Welcome to the Pkl community, and thank you for contributing! This guide explains how to get involved.

• Licensing

• Issue Tracking

• Pull Requests

Licensing

Pkl is released under the Apache 2.0 license. This is why we require that, by submitting a pull request, you acknowledge that you have the right to license your contribution to Apple and the community, and agree that your contribution is licensed under the Apache 2.0 license.

Issue Tracking

To file a bug or feature request, use GitHub. Be sure to include the following information:

• Context

  • What are/were you trying to achieve?

  • What’s the impact of this bug/feature?

For bug reports, additionally include the following information:

• The output of pkl --version.

• The complete error message.

• The simplest possible steps to reproduce.

Pull Requests

When preparing a pull request, follow this checklist:

• Imitate the conventions of surrounding code.

• Format code with ./gradlew spotlessApply (otherwise the build will fail).

• Verify that both the JVM build (./gradlew build) and native build (./gradlew buildNative) succeed.

• Follow the seven rules of great Git commit messages:

  • Separate subject from body with a blank line.

  • Limit the subject line to 50 characters.^[1]

  • Capitalize the subject line.

  • Do not end the subject line with a period.

  • Use the imperative mood in the subject line.

  • Wrap the body at 72 characters.^[1]

  • Use the body to explain what and why vs. how.

Important

If you plan to make substantial changes or add new features, we encourage you to first discuss them with the wider Pkl developer community. You can do this by filing a GitHub Issue or by starting GitHub Discussion. This will save time and increases the chance of your pull request being accepted.

Maintainers

The project’s maintainers (those with write access to the upstream repository) are listed in MAINTAINERS.adoc.

---

1. This rule is not enforced in the Pkl project.