Skip to content

Latest commit

 

History

History
121 lines (86 loc) · 4.72 KB

CONTRIBUTING.md

File metadata and controls

121 lines (86 loc) · 4.72 KB
Raw

Contributing

Welcome to the urfave/cli contributor docs! This goal of this document is to help those interested in joining the 200+ humans who have contributed to this project over the years.

As a general guiding principle, the current maintainers may be notified via the @urfave/cli GitHub team.

All of the current maintainers are volunteers who live in various timezones with different scheduling needs, so please understand that your contribution or question may not get a response for many days.

semantic versioning adherence

The urfave/cli project strives to strictly adhere to semantic versioning. The active development branches and the milestones and import paths to which they correspond are:

main branch

https://github.com/urfave/cli/tree/main

The majority of active development and issue management is targeting the main branch, which MUST only receive bug fixes and feature additions.

  • ➡️ v2.x
  • ➡️ github.com/urfave/cli/v2

The main branch in particular includes tooling to help with keeping the v2.x series backward compatible. More details on this process are in the development workflow section below.

v1 branch

https://github.com/urfave/cli/tree/v1

The v1 branch MUST only receive bug fixes in the v1.22.x series. There is no strict rule regarding bug fixes to the v2.x series being backported to the v1.22.x series.

  • ➡️ v1.22.x
  • ➡️ github.com/urfave/cli

v3-dev-main branch

https://github.com/urfave/cli/tree/v3-dev-main

The v3-dev-branch MUST receive all bug fixes and features added to the main branch and MAY receive feature removals and other changes that are otherwise backward-incompatible with the v2.x series.

  • ➡️ v3.x
  • unreleased / unsupported

development workflow

Most of the tooling around the development workflow strives for effective dogfooding. There is a top-level Makefile that is maintained strictly for the purpose of easing verification of one's development environment and any changes one may have introduced:

make

Running the default make target (all) will ensure all of the critical steps are run to verify one's changes are harmonious in nature. The same steps are also run during the continuous integration phase.

In the event that the v2diff target exits non-zero, this is a signal that the public API surface area has changed. If the changes adhere to semantic versioning, meaning they are additions or bug fixes, then manually running the approval step will "promote" the current go doc output:

make v2approve

Because the generate step includes updating godoc-current.txt and testdata/godoc-v2.x.txt, these changes MUST be part of any proposed pull request so that reviewers have an opportunity to also make an informed decision about the "promotion" step.

generated code

A significant portion of the project's source code is generated, with the goal being to eliminate repetetive maintenance where other type-safe abstraction is impractical or impossible with Go versions < 1.18. In a future where the eldest Go version supported is 1.18.x, there will likely be efforts to take advantage of generics.

The built-in go generate command is used to run the commands specified in //go:generate directives. Each such command runs a file that also supports a command line help system which may be consulted for further information, e.g.:

go run internal/genflags/cmd/genflags/main.go --help

pull requests

Please feel free to open a pull request to fix a bug or add a feature. The @urfave/cli team will review it as soon as possible, giving special attention to maintaining backward compatibility. If the @urfave/cli team agrees that your contribution is in line with the vision of the project, they will work with you to get the code into a mergeable state, merged, and then released.

granting of commit bit / admin mode

Those with a history of contributing to this project will likely be invited to join the @urfave/cli team. As a member of the @urfave/cli team, you will have the ability to fully administer pull requests, issues, and other repository bits.

If you feel that you should be a member of the @urfave/cli team but have not yet been added, the most likely explanation is that this is an accidental oversight! 😅. Please open an issue!