:uri-github-discussion: https://github.com/apple/pkl/discussions
:uri-github-issue-pkl: https://github.com/apple/pkl/issues/new
:uri-seven-rules: https://cbea.ms/git-commit/#seven-rules

= 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 {uri-github-issue-pkl}[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 {uri-seven-rules}[seven rules] of great Git commit messages:
** Separate subject from body with a blank line.
** Limit the subject line to 50 characters.footnote:not-enforced[This rule is not enforced in the Pkl project.]
** 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.footnote:not-enforced[]
** 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 {uri-github-issue-pkl}[GitHub Issue] or by starting
{uri-github-discussion}[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 link:MAINTAINERS.adoc[].