lucene/dev-docs/github-issues-howto.md

<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
-->

# GitHub Issues How-To Manual

## Milestones

We use Milestones for release planning.

A milestone represents a release. Issues and/or PRs should be associated with proper Milestones where the changes are planned to be delivered.

All issues/PRs associated with a milestone must be resolved before the release, which means unresolved issues/PRs in a milestone are blockers for the release. Release managers should consider how to address blockers. Some may be resolved by developers, and others may be postponed to future releases.

Once the release is done, the Milestone should be closed then a new Milestone for the next release should be created.

You can see the list of current active (opened) Milestones here. https://github.com/apache/lucene/milestones

See [GitHub documentation](https://docs.github.com/en/issues/using-labels-and-milestones-to-track-work/about-milestones) for more details.

### Relation between Milestones and CHANGES

The Milestone associated with an Issue/PR should be the same version in [CHANGES](https://github.com/apache/lucene/blob/main/lucene/CHANGES.txt). For instance, if an Issue/PR appears in the CHANGES section 10.0.0, it should be marked as Milestone 10.0.0.

## Issue labels

There are a few pre-defined label families to organize/search issues.

- `type` (color code `#ffbb00`) : issue type
  - `type:bug` is attached to bug reports
  - `type:enhancement` is attached to enhancement requests or suggestions
  - `type:test` is attached to test improvements or failure reports
  - `type:task` is attached to general tasks
  - `type:documentation` is attached to tasks relate to documentation
- `affects-version` (color code `#f19072`) : the versions in which a bug was found 
  - this may be used with `type:bug` 
  - (example) `affects-version:9.1.0`
- `module` (color code `#a0d8ef`) : Lucene module
  - (example) `module:core/index`, `module:analysis`
- `tool` (color code `#a0d8ef`) : tooling
  - (example) `tool:build`, `tool:release-wizard`

A `type` label is automatically attached to an issue by the issue template that the reporter selected. Other labels such as `affects-version` may be manually added by committers.

If necessary, uncategorized labels may also be used.

- `good first issue`
- `discuss`
- `duplicate`
- `website`

Committers can add/edit labels manually or programmatically using [Labels API](https://docs.github.com/en/rest/issues/labels).

## Issue templates

Each issue template (web form) is associated with one `type` label. You should add an issue template when adding a new `type` label and vice versa.

- `Bug Report` is associated with `type:bug` label
- `Enhancement Request/Suggestion` is associated with `type:enhancement` label
- `Test Improvement / Failure Report` is associated with `type:test` label
- `Task` is associated with `type:task` label
- `Documentation` is associated with `type:documentation` label

Issue templates are written in YAML format and committed in `.github/ISSUE_TEMPLATE`. See [GitHub documentation](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms) for details.

## Should I raise an Issue when I already have a working patch?

It's up to you.

From a broader viewpoint, there are no differences between issues and pull requests. You can associate both issues and PRs with Milestones/Labels and mention both issues and PRs in the CHANGES in the very same manner. Sometimes a pull request would be sufficient, and sometimes you may want to open an issue and PRs on it, depending on the context.