opensource/podman
1
0
Fork 0
mirror of https://github.com/containers/podman.git synced 2025-05-17 06:59:07 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add documentation describing issues and support

Browse Source 
We need to begin to able to prune various issues that are:

* stale
* unreproduceable
* will not fix
* others

As such, some sort of statement and somewhat policy leaning
documentation would be helpful.

As suggested in the review comments, ISSUE-EOL-POLICY.md was combined
with this document.  No links in our repository exist for this.

Signed-off-by: Brent Baude <bbaude@redhat.com>
This commit is contained in:
Brent Baude
2025-02-07 10:29:21 -06:00
parent 10ab978c26
commit a8caebb5a3
4 changed files with 169 additions and 76 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.github/ISSUE_TEMPLATE/bug_report.yaml vendored
View File

@ -5,7 +5,7 @@ body:
- type: markdown
attributes:
value: |
Thanks for taking the time to fill out this bug report!
Thanks for taking the time to fill out this bug report! For extended guidelines on reporting issues, please consult the [issue reporting](https://github.com/containers/podman/blob/main/ISSUE.md) documentation. You should also familiarize yourself with our [support](https://github.com/containers/podman/blob/main/SUPPORT.md) documentation.
**NOTE** A large number of issues reported against Podman are often found to already be fixed in more current versions of the project. Before reporting an issue, please verify the version you are running with `podman version` and compare it to the latest release documented on the top of Podman's [README.md](https://github.com/containers/podman#readme). If they differ, please update your version of Podman to the latest possible and retry your command before creating an issue.

75
ISSUE-EOL-POLICY.md
View File

@ -1,75 +0,0 @@
# End-of-Life Policy on Issues
_jetsam (n): the part of a ship, its equipment, or its cargo that is cast overboard to lighten the load in time of distress_
Finite resources demand some level of pruning. This document describes
the basic principles used by the Containers team to identify and close
stale issues.
------
## Definitions
[**stale**](https://github.com/containers/podman/issues?q=is%3Aopen+is%3Aissue+sort%3Acreated-asc+label%3Astale-issue): open, but no activity in the last thirty days.
**crickets**: closed due to lack of response from reporting party.
[**jetsam**](https://github.com/containers/podman/issues?q=is%3Aissue+label%3Ajetsam+is%3Aclosed): closed without being implemented. A deliberate decision made in recognition of human limitations.
------
## Process
In order of judgment, from least to most.
#### &rarr; stale
Issues are marked with the label *stale-issue* by a [github action](https://github.com/containers/podman/blob/main/.github/workflows/stale.yml) that runs daily at 00:00 UT. This also triggers an email alert to subscribers on that issue.
Judgment: typically a team member will skim the issue, then decide whether to:
* remove the label; or
* close the issue (see below); or
* do nothing.
This is informal: there is no guarantee that anyone will actually do this.
#### &rarr; crickets
Typically done by a team member after receiving a *stale-issue* email.
Judgment:
* there is not enough information to act on the issue; and
* someone on the team has asked the reporter for more details (like NEEDINFO); and
* the reporter has not responded.
There is no actual *crickets* label. There is no automated way to
find issues that have been closed for this reason.
#### &rarr; jetsam
Last-resort closing of an issue that will not be worked on.
Factors:
* issue has remained open for over sixty days; and
* reporter is responsive, and still wishes to have the issue addressed (as does the team).
Judgment:
* the issue is too difficult or complicated or hard to track down.
* decision should be made by two or more team members, with discussion in the issue/PR itself.
When such an issue is closed, team member should apply the *jetsam* label.
------
## Grayer Areas
`stalebot` isn't perfect. It often misses issues, and we end up with
some that have been open a long time and do not have the `stale-issue` label.
These are hard to find manually. There is no defined process for identifying
or acting on them. If and when someone finds these, they should be handled
through the process defined above.

123
ISSUE.md Normal file
View File

@ -0,0 +1,123 @@
# Issue reporting on Podman
The Podman team cares for our users and our communities. When someone has a problem with
Podman and takes the time to report an [issue](https://github.com/containers/podman/issues)
on our Github, we deeply appreciate the effort. We want to help. Consider reading
our [support](SUPPORT.md) document prior to submitting an issue as well.
## Considerations when reporting an issue upstream
### Where to report your issue
If you are running Podman acquired from a Linux distribution and that Linux distribution has a
bug reporting mechanism, then please report the bug there. To report an issue on our
github repository, use the issue tab and click [New Issue](https://github.com/containers/podman/issues/new/choose)
### Development or latest version
We view this Github repository as an upstream repository for development of the latest
of Podman in the main branch.
When reporting an issue, it should ideally be for the main branch of our repository. Please make
an effort to reproduce the issue using the main branch whenever possible. An issue can also
be written against the latest released version of Podman.
The term "latest version" refers to our mainline development tree or the
[latest release](https://github.com/containers/podman/releases/latest).
### Bugs vs features
A bug is when something in Podman is not working as it should or has been described. A
feature or enhancement is when you would like Podman to behave differently.
### Use the issue template when reporting bugs
When you report an issue on the upstream repository, be sure to fill out the entire template.
You must provide the required `podman info` wherever possible as it helps us diagnose
your report. If possible, always provide a _reliable reproducer_. This is extremely
helpful for us during triage and bug fixing. Good examples of a reliable repoducer are:
* Provide precise Podman commands
* Use generic images (like fedora/alpine/debian) where possible to reduce the chance your
container images was a contributor. Abstracting away from the functional purpose helps
diagnoses and reduces noise for us.
* If using the RESTFUL API, providing curl commands as a repoducer is preferred. Be sure
to provide the same data (or sample data) for things like POST.
* Not requiring the use of a third party tool to reproduce the problem
### Look through existing issues before reporting a new issue
Managing issues is a time consuming processes for maintainers. You can save us time by
making sure the issue you want to report has not already been reported. It is appropriate
to comment on the existing issue with relevant information.
### Why was my issue report closed
Issues filed upstream may be closed by a maintainer for the following reasons:
* A fix for the issue has been merged into the main branch of our upstream
repository. It is possible that the bug was already fixed upstream as well.
* The reported issue is a duplicate.
* The issue is reported against a [distribution that has a bug reporting mechanism](#where-to-report-your-issue)
or paid support.
* The issue was reported using an [older version](#development-or-latest-version) of Podman.
* A maintainer determines the code is working as designed.
* The issue has become [stale](#-stale) and reporters are not responding.
* We were unable to reproduce the issue, or there was insufficient information to reproduce the issue.
* One or more maintainers have decided a feature will not be implemented or an issue will not be fixed.
#### Definitions
[**stale**](https://github.com/containers/podman/issues?q=is%3Aopen+is%3Aissue+sort%3Acreated-asc+label%3Astale-issue): open, but no activity in the last thirty days.
**crickets**: closed due to lack of response from reporting party.
[**jetsam**](https://github.com/containers/podman/issues?q=is%3Aissue+label%3Ajetsam+is%3Aclosed): closed without being implemented. A deliberate decision made in recognition of human limitations.
#### Process
In order of judgment, from least to most.
##### &rarr; stale
Issues are marked with the label *stale-issue* by a [github action](https://github.com/containers/podman/blob/main/.github/workflows/stale.yml) that runs daily at 00:00 UT. This also triggers an email alert to subscribers on that issue.
Judgment: typically a team member will skim the issue, then decide whether to:
* remove the label; or
* close the issue (see below); or
* do nothing.
This is informal: there is no guarantee that anyone will actually do this.
##### &rarr; crickets
Typically done by a team member after receiving a *stale-issue* email.
Judgment:
* there is not enough information to act on the issue; and
* someone on the team has asked the reporter for more details (like NEEDINFO); and
* the reporter has not responded.
There is no actual *crickets* label. There is no automated way to
find issues that have been closed for this reason.
##### &rarr; jetsam
Last-resort closing of an issue that will not be worked on.
Factors:
* issue has remained open for over sixty days; and
* reporter is responsive, and still wishes to have the issue addressed (as does the team).
Judgment:
* the issue is too difficult or complicated or hard to track down.
* decision should be made by two or more team members, with discussion in the issue/PR itself.
When such an issue is closed, team member should apply the *jetsam* label.

45
SUPPORT.md Normal file
View File

@ -0,0 +1,45 @@
# Upstream support of Podman
This Github repository is for the upstream development of Podman and the latest version
of Podman.
The term "latest version" refers to our mainline development tree or the
[latest release](https://github.com/containers/podman/releases/latest).
## Expectations on support
The Podman maintainers provide a "best effort" for the support of Podman. If are using
Podman from a Linux distribution, please use the Linux distribution's mechanism as support
unless you are willing to reproduce problems on the main branch of our upstream code.
## Operating System and Hardware
Podman is run on a bevy of operating systems and hardware. Upstream development cannot
possibly support all the combinations and custom environments of our users.
All pull requests (new code) to Podman go through automated testing on the following
combinations:
### Native Podman
| Architecture | Operating System | Distribution |
| :--- | :--- | :--- |
| x86_64 | Linux | Debian (latest) |
| x86_64 | Linux | Fedora (latest) |
| ARM64 | Linux | Fedora (latest) |
### Podman Machine
| Architecture | Operating System | Machine Provider |
| :--- | :--- | :--- |
| x86_64 | Windows 2022 | WSL |
| x86_64 | Windows 2022 | HyperV |
| ARM64 | MacOS | AppleHV |
| ARM64 | MacOS | Libkrun |
For Linux, we test the latest versions of Fedora and Debian.
Operating systems and hardware outside our automated testing is considered "best effort".
In many cases, we are unable to test, triage, and develop for combinations outside what
our automated testing covers. For example, Podman on Intel-based Macs.