Skip to content

Latest commit

 

History

History
154 lines (110 loc) · 6.26 KB

CONTRIBUTING.md

File metadata and controls

154 lines (110 loc) · 6.26 KB
Raw

Contributing

Hello!

Thank you for your interest in contributing to the listen.dev CLI!

We accept pull requests for bug fixes and features where we've discussed the approach in an issue and given the go-ahead for a community member to work on it. We'd also love to hear about ideas for new features as issues.

Please do:

  • Check existing issues to verify that the bug or feature request has not already been submitted.
  • Open an issue if things aren't working as expected.
  • Open an issue to propose a significant change.
  • Open a pull request to fix a bug.
  • Open a pull request to fix documentation about a command.
  • Open a pull request for any issue labelled help wanted or good first issue.

Please avoid:

  • Opening pull requests for issues marked needs-design, needs-investigation, or blocked.
  • Opening pull requests for any issue marked core.
    • These issues require additional context from the core CLI team and any external pull requests will not be accepted.

Building the CLI

Prerequisites:

  • Go 1.21+

Build with:

go build -o make/make make/main.go
make/make lstn

Run the CLI as:

./lstn help

Testing the CLI

Run tests with: go test ./...

Documenting the CLI

See project layout documentation for information on where to find specific source files.

We generate manual pages from source on every release. You do not need to submit pull requests for documentation specifically; manual pages for commands will automatically get updated after your pull requests gets accepted.

Commit convention

We enforce the commits to follow the Conventional Commits v1.0 spec with the following (the default one) set of prefixes:

build
you're changing something in the build system
ci
you're taking care of our CI and automation
chore
little changes like typos; generally nothing very significant
docs
you are helping us with documentation
feat
your changes implement a new feature or update an existing one
fix
we'll always be grateful to you for your bug fixes
perf
you wrote a beautiful Go benchmark
refactor
when you are moving pieces around, changing file names, etc.
revert
you're reverting some changes: it may happen
test
your changes introduce, extend, or update some tests

Let us now provide you some examples of commit messages we accept:

chore: make linter happy
chore: fix a little typo
test: check edge case X doesn't happen
fix: ensure edge case X doesn't verify anymore
feat(cmd/in): support reading package.json from remote URLs
docs: improve the commit convention examples
build: make the manpages
fix!: change listen.Packages API

Notice that by using ! after the prefix and before the colon you are communicating breaking changes.

Enforcing the commits to follow this convention helps us:

  • keep the commit history readable
  • have an easily understandable commit history
  • manually label the pull requests accordingly

Thank you for sticking to using it!

Notice that we check the commit messages and lint them on every pull request. Should you find some bugs with the commit linting process, you can notify the author of the underlying parser at leodido/go-conventionalcommits.

Notice also that the enforcement of the Conventional Commit v1.0 spec is from v0.1.0 onwards, previous git history may not follow it perfectly.

Submitting a pull request

We also enforce the pull requests titles to follow the Conventional Commits v1.0 spec.

This because we have machinery in place that automatically labels the pull requests depending on the:

  • the path and file changes
  • the title of the pull request
  • the branch name of the pull request

You can see the rules we use here.

It helps us automatically generate a wonderful changelog!

Let's say that you spot a bug and you wanna fix it... You can open a pull request from a branch like fix/some-subtle-bug and it will be automatically labeled with the bug label. Or you can just use the title fix: some subtle bug.

  1. Create a new branch: git checkout -b fix/some-subtle-bug
  2. Make your change, add tests, and ensure tests pass
  3. Submit a pull request: gh pr create --web

Please write small pull requests to ease our review and maintenance burdens.

Contributions to this project are released to the public under the project's open source license.

Please note that this project adheres to a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Resources