Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 81 additions & 0 deletions .github/ISSUE_TEMPLATE/01-bug-report.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
name: Bug report
description: A reproducible failure with no standard in play
labels: ["bug"]
body:
- type: markdown
attributes:
value: |
Use this for a crash, a result that contradicts the library's own documentation,
or a broken installation.

A value that disagrees with a standard or with a reference implementation is not
this, even when it reproduces every time. That goes to
[Standards & conformance](https://github.com/jmrplens/phonometry/discussions/categories/standards-conformance),
because settling it means reading the clause first.

- type: textarea
id: what
attributes:
label: What happens
description: What you observed, and what you expected instead.
validations:
required: true

- type: textarea
id: reproduce
attributes:
label: Minimal reproducible example
description: >
Self-contained code that fails when run. If it needs a signal, generate it in the
snippet rather than attaching a file where you can.
render: python
validations:
required: true

- type: textarea
id: traceback
attributes:
label: Traceback or output
description: The full traceback if it raises, or the values you got if it does not.
render: text
validations:
required: false

- type: input
id: version
attributes:
label: phonometry version
description: 'Run: python -c "import phonometry; print(phonometry.__version__)"'
placeholder: "3.3.0"
validations:
required: true

- type: input
id: environment
attributes:
label: Python version and operating system
placeholder: "Python 3.13 on Ubuntu 24.04"
validations:
required: true

- type: dropdown
id: install
attributes:
label: How did you install it?
options:
- pip from PyPI
- conda or mamba
- from source
- other
validations:
required: false

- type: checkboxes
id: checks
attributes:
label: Before submitting
options:
- label: This is not a disagreement with a standard or a reference implementation.
required: true
- label: I am on the latest released version, or I checked that the problem is still present there.
required: false
80 changes: 80 additions & 0 deletions .github/ISSUE_TEMPLATE/02-conformance-defect.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,80 @@
name: Conformance defect
description: A confirmed disagreement between the library and a standard
labels: ["conformance"]
body:
- type: markdown
attributes:
value: |
For a discrepancy that has already been established: the library computes a value
that does not match what the standard requires.

If it has not been looked at yet, start in
[Standards & conformance](https://github.com/jmrplens/phonometry/discussions/categories/standards-conformance)
instead. Most reported discrepancies turn out to be a different edition, a
different clause, or a difference in the input conditions, and the discussion is
where that gets sorted out.

**Cite clauses and tables by number rather than pasting the text.** Standards are
copyrighted.

- type: input
id: discussion
attributes:
label: Discussion where this was established
description: Leave empty only if the defect is self-evident from the numbers below.
placeholder: "https://github.com/jmrplens/phonometry/discussions/..."
validations:
required: false

- type: input
id: standard
attributes:
label: Standard, edition and year
placeholder: "IEC 61672-1:2013"
validations:
required: true

- type: input
id: clause
attributes:
label: Clause, table, annex or equation
placeholder: "Clause 5.4.11, Table 3, Eq. (12)"
validations:
required: true

- type: input
id: api
attributes:
label: Function or module affected
placeholder: "phonometry.levels.equivalent_level"
validations:
required: true

- type: textarea
id: numbers
attributes:
label: Required value against computed value
description: >
State both, with the input conditions they correspond to, and say where the
required value comes from. Tolerances matter: give the one the standard allows.
validations:
required: true

- type: textarea
id: reproduce
attributes:
label: Code that reproduces it
render: python
validations:
required: true

- type: dropdown
id: origin
attributes:
label: Where does the defect appear to be?
options:
- In the library
- In the published standard itself, and belongs in docs/ERRATA.md
- Not established yet
validations:
required: false
83 changes: 83 additions & 0 deletions .github/ISSUE_TEMPLATE/03-new-standard.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,83 @@
name: Implement a standard or method
description: An agreed piece of work to cover something not implemented yet
labels: ["new standard"]
body:
- type: markdown
attributes:
value: |
This is a work item, not a proposal. Open proposals in
[Ideas](https://github.com/jmrplens/phonometry/discussions/categories/ideas)
first, where the scope and the validation data get worked out.

What decides whether this can be built is the reference data. Every method here
comes from the standard itself and is checked against normative values, so an
item without an oracle stays blocked no matter how well specified it is.

- type: input
id: standard
attributes:
label: Standard, edition and year
description: Or the paper or book, if no standard defines the method.
placeholder: "ISO 3382-2:2008"
validations:
required: true

- type: textarea
id: scope
attributes:
label: Scope
description: >
Which clauses, tables and annexes are in, and which are deliberately out. Being
explicit about the exclusions is what keeps the conformance claim honest.
validations:
required: true

- type: input
id: module
attributes:
label: Proposed module and public names
description: >
A concept name in snake_case, never a standard number. See the naming conventions
in CONTRIBUTING.md.
placeholder: "room/reverberation_time.py, reverberation_time()"
validations:
required: false

- type: textarea
id: oracle
attributes:
label: Reference data for validation
description: >
Worked examples in the standard, published tables, a reference implementation, or
measurements. Say which of these is available and where it is, or state plainly
that none is known.
validations:
required: true

- type: dropdown
id: source
attributes:
label: Is the document itself available?
options:
- Yes, available
- No, needs to be obtained
- Partially, only the parts quoted in secondary sources
validations:
required: true

- type: checkboxes
id: deliverables
attributes:
label: Deliverables
description: The usual set for a new method. Untick anything that does not apply.
options:
- label: Implementation with type annotations
required: false
- label: Tests against the reference values, including edge cases
required: false
- label: Conformance check registered in the report
required: false
- label: Teaching-style guide page, English and Spanish
required: false
- label: Figure generated by scripts/generate_graphs.py
required: false
55 changes: 55 additions & 0 deletions .github/ISSUE_TEMPLATE/04-documentation.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
name: Documentation defect
description: Something in the documentation is wrong or broken
labels: ["documentation"]
body:
- type: markdown
attributes:
value: |
For a concrete defect: a wrong value or formula, an example that no longer runs, a
broken link, a figure that does not match the text.

If an explanation is simply hard to follow, or a guide is missing, that is
[Documentation & learning](https://github.com/jmrplens/phonometry/discussions/categories/documentation-learning)
instead. It is worth raising there, it just does not start as an issue.

- type: input
id: page
attributes:
label: Page
description: The URL on the documentation site, or the file under docs/.
placeholder: "https://jmrplens.github.io/phonometry/guides/filter-banks/"
validations:
required: true

- type: dropdown
id: language
attributes:
label: Language
options:
- English
- Spanish
- Both
validations:
required: true

- type: dropdown
id: kind
attributes:
label: What is wrong?
options:
- A wrong value, formula or unit
- An example that does not run
- Documented behaviour that does not match the library
- A broken link or a missing image
- A figure that disagrees with the text
- Something else
validations:
required: true

- type: textarea
id: detail
attributes:
label: What it says, and what it should say
description: Quote the passage. If you know the correction, give it.
validations:
required: true
Loading