Merge remote-tracking branch 'origin/main' into security-policy-doc
This commit is contained in:
@@ -1,3 +1,9 @@
|
||||
> :warning: This document is no longer being actively maintained. Please see the
|
||||
> [releases page](https://github.com/urfave/cli/releases) for all release notes
|
||||
> and related hypermedia for releases `>= 1.22.5`, `>= 2.3.0`.
|
||||
|
||||
---
|
||||
|
||||
# Change Log
|
||||
|
||||
**ATTN**: This project uses [semantic versioning](http://semver.org/).
|
||||
|
||||
@@ -1,18 +1,121 @@
|
||||
## Contributing
|
||||
|
||||
Use @urfave/cli to ping the maintainers.
|
||||
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.
|
||||
|
||||
Feel free to put up a pull request to fix a bug or maybe add a feature. We will
|
||||
give it a code review and make sure that it does not break backwards
|
||||
compatibility. If collaborators agree that it is in line with
|
||||
the vision of the project, we will work with you to get the code into
|
||||
a mergeable state and merge it into the main branch.
|
||||
> As a general guiding principle, the current maintainers may be notified via the
|
||||
> @urfave/cli GitHub team.
|
||||
|
||||
If you have contributed something significant to the project, we will most
|
||||
likely add you as a collaborator. As a collaborator you are given the ability
|
||||
to merge others pull requests. It is very important that new code does not
|
||||
break existing code, so be careful about what code you do choose to merge.
|
||||
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.
|
||||
|
||||
If you feel like you have contributed to the project but have not yet been added
|
||||
as a collaborator, we probably forgot to add you :sweat_smile:. Please open an
|
||||
issue!
|
||||
### semantic versioning adherence
|
||||
|
||||
The `urfave/cli` project strives to strictly adhere to [semantic
|
||||
versioning](https://semver.org/spec/v2.0.0.html). 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*.
|
||||
|
||||
- :arrow_right: [`v2.x`](https://github.com/urfave/cli/milestone/16)
|
||||
- :arrow_right: `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.
|
||||
|
||||
- :arrow_right: [`v1.22.x`](https://github.com/urfave/cli/milestone/11)
|
||||
- :arrow_right: `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.
|
||||
|
||||
- :arrow_right: [`v3.x`](https://github.com/urfave/cli/milestone/5)
|
||||
- unreleased / unsupported
|
||||
|
||||
### development workflow
|
||||
|
||||
Most of the tooling around the development workflow strives for effective
|
||||
[dogfooding](https://en.wikipedia.org/wiki/Eating_your_own_dog_food). 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:
|
||||
|
||||
```sh
|
||||
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](https://github.com/urfave/cli/blob/main/.github/workflows/cli.yml).
|
||||
|
||||
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:
|
||||
|
||||
```sh
|
||||
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](https://go.dev/doc/tutorial/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.:
|
||||
|
||||
```sh
|
||||
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! :sweat_smile:.
|
||||
Please open an issue!
|
||||
|
||||
<!--
|
||||
vim:tw=90
|
||||
-->
|
||||
|
||||
61
docs/RELEASING.md
Normal file
61
docs/RELEASING.md
Normal file
@@ -0,0 +1,61 @@
|
||||
# Releasing urfave/cli
|
||||
|
||||
Releasing small batches often is [backed by
|
||||
research](https://itrevolution.com/accelerate-book/) as part of the
|
||||
virtuous cycles that keep teams and products healthy.
|
||||
|
||||
To that end, the overall goal of the release process is to send
|
||||
changes out into the world as close to the time the commits were
|
||||
merged to the `main` branch as possible. In this way, the community
|
||||
of humans depending on this library are able to make use of the
|
||||
changes they need **quickly**, which means they shouldn't have to
|
||||
maintain long-lived forks of the project, which means they can get
|
||||
back to focusing on the work on which they want to focus. This also
|
||||
means that the @urfave/cli team should be able to focus on
|
||||
delivering a steadily improving product with significantly eased
|
||||
ability to associate bugs and regressions with specific releases.
|
||||
|
||||
## Process
|
||||
|
||||
- Release versions follow [semantic versioning](https://semver.org/)
|
||||
- Releases are associated with **signed, annotated git tags**[^1].
|
||||
- Release notes are **automatically generated**[^2].
|
||||
|
||||
In the `main` or `v1` branch, the current version is always
|
||||
available via:
|
||||
|
||||
```sh
|
||||
git describe --always --dirty --tags
|
||||
```
|
||||
|
||||
**NOTE**: if the version reported contains `-dirty`, this is
|
||||
indicative of a "dirty" work tree, which is not a great state for
|
||||
creating a new release tag. Seek help from @urfave/cli teammates.
|
||||
|
||||
For example, given a described version of `v2.4.7-3-g68da1cd` and a
|
||||
diff of `v2.4.7...` that contains only bug fixes, the next version
|
||||
should be `v2.4.8`:
|
||||
|
||||
```sh
|
||||
git tag -a -s -m 'Release 2.4.8' v2.4.8
|
||||
git push origin v2.4.8
|
||||
```
|
||||
|
||||
The tag push will trigger a GitHub Actions workflow. The remaining
|
||||
steps require human intervention through the GitHub web view
|
||||
although [automated solutions
|
||||
exist](https://github.com/softprops/action-gh-release) that may be
|
||||
adopted in the future.
|
||||
|
||||
- Open the [the new release page](https://github.com/urfave/cli/releases/new)
|
||||
- At the top of the form, click on the `Choose a tag` select control and select `v2.4.8`
|
||||
- In the `Write` tab below, click the `Auto-generate release notes` button
|
||||
- At the bottom of the form, click the `Publish release` button
|
||||
- :white_check_mark: you're done!
|
||||
|
||||
[^1]: This was not always true. There are many **lightweight git
|
||||
tags** present in the repository history.
|
||||
|
||||
[^2]: This was not always true. The
|
||||
[`docs/CHANGELOG.md`](./CHANGELOG.md) document used to be
|
||||
manually maintained.
|
||||
Reference in New Issue
Block a user