Issues
how issues are organized, how to branch, do PRs, etc
§ How to File an Issue
Fixing bugs is part of our job, but it's not always easy to find the problem correctly and quickly, so we ask for a little help in reporting it to us, in this way we can be faster in solving it.
All reports are collected in the Issue Tracker of the EPUBCheck repository on GitHub. To report a problem just add a new issue.
In order to be able to check and fix the bug as soon as possible, we need to be able to replicate it locally; for this we need to know the environment in which you are operating, in particular:
- which EPUBCheck version you are using (you can use the command
java -jar epubcheck.jar --versionto get it) - which Java version is installed (you can use the
java --versioncommand to get it) - which Operating System you're using (Windows, macOS or Linux) and which version
In addition, too be able to replicate the problem we would need:
- an accurate description of the steps taken (e.g. commands used, etc.)
- in some cases, a test file to help us highlight the problem immediately. Since the EPUBCheck operations are closely related to the files checked, for the resolution of several bugs it is important to be able to test the tool with the files that generated the bugs; if the file cannot be made public:
- you can try to make an excerpt of it, proposing only the part of the code related to the problem
- or you can ask in the issue to be contacted by one of the developers to whom you can send the file privately
§ Labels Reference
In order not to get lost among the many issues to manage, we have set up a label system that allows us to quickly identify the various problems according to type, severity and urgency.
The various labels can be combined to describe an issue, for example priority: low type: maintenance status: accepted means that the issue is actually to be fixed, but with low priority (when there will be time) and that it is related to software maintenance operations.
In the following table we explain the organization of the labels.
| Label | Short description | Long description |
|---|---|---|
| dependencies | Pull requests that update a dependency file | |
| newcomers friendly 😊 | This issue can be picked up by newcomers to the project! | The issue is easy to manage, so it can be used by new contributors to gain experience |
| priority: critical | To be processed and published ASAP | It means that the issue is extremely severe - the problem affects the use of the software - so it must be solved as soon as possible, without waiting for a new release |
| priority: high | To be processed and published in the next release | The issue is high level, but not blocking for the software, it will be resolved in the next release |
| priority: low | To be processed when time allows | The issue is a acknowledged problem, but not an urgent one, so it will be solved when the developers manage to dedicate some time to it |
| priority: medium | To be processed and published in one of the upcoming releases | A problem validated and to be solved, but that does not prevent the use of the tool, will be worked on for one of the next releases |
| spec: EDUPUB | Impacting the support of the EDUPUB specification | This issue is related to the technical specifications of EDUPUB Profile |
| spec: EPUB 2.x | Impacting the support of EPUB 2.x specifications | The issue is related to the technical specifications of EPUB 2 |
| spec: EPUB 3.2 | Impacting the support of EPUB 3.2 | The issue is related to the technical specifications of EPUB 3.2 |
| spec: EPUB 3.x | Impacting the support of EPUB 3.x specifications | The issue is related to the technical specifications of EPUB 3 |
| spec: all | Impacting the support of all EPUB specifications | The issue is related to all the technical specifications: EPUB 2, EPUB 3, EPUB 3.2 and EDUPUB Profile |
| status: accepted | Ready to be further processed | The issue has been checked and queued up to be resolved, wait to be picked up by a developer |
| status: blocked | Blocked by another issue or situation | The issue cannot be fixed because it is blocked (or pending) by another issue or by a situation, more details in the comments of the issue |
| status: completed | Work completed, can be closed | The development work to fix the issue has been completed, the issue can be closed |
| status: has PR | The issue is being processed in a pull request | The issue is worked in a different branch and will be merged to the main code with a Pull Request procedure |
| status: in discussion | The issue is being discussed by the development team | The issue is being discussed by members of the development team, updates will be available in comments |
| status: in progress | The issue is being implemented by the development team | The issue is under development, will soon be solved |
| status: needs review | Needs to be reviewed by a team member before further processing | The issue needs to be analyzed by a developer for further insight |
| status: ready for implem | The issue is ready to be implemented | The issue has been analyzed and is ready to be developed, according to the priority I will be processed by the developers |
| status: ready to merge | The pull request is ready to be merged | The issue has been developed outside the main branch, the Pull Request procedure has been started, the work done has been analyzed by the team members and is ready to be merged with the main code |
| status: stalled | The issue has been inactive for a while | The discussion on this issue has been inactive for some time, that's why it has been hibernated |
| status: waiting for feedback | The development team needs feedback from the issue’s creator | The issue is not clear or needs further clarification by the creator (e.g. information about the working environment, test files, etc.) |
| type: bug | The issue describes a bug | The issue is related to a programming bug of the tool |
| type: docs | The issue is related to documentation | The issue is about [this] documentation: user guide, developer guide, tutorials, etc. |
| type: duplicate | The issue duplicates an existing issue | The issue is a duplicate of another issue, more details in the comments |
| type: false-negative | This issue is about invalid content being incorrectly accepted | The issue has identified a problem of false negative: of the content that should have generated warnings or errors, instead it passed without problems |
| type: false-positive | This issue is about valid content being incorrectly rejected | The issue has identified a problem of false positive: of the content reported as warning or error, it is actually correct and should not generate messages |
| type: feature | The issue describes a new feature request | The issue is related to a functionality that is not currently available in the tool, but that can be better analyzed and possibly taken into account for future developments |
| type: improvement | The issue suggests an improvement of an existing feature | The issue proposes an improvement in the functioning of the tool's already assistant functionalities, to be analyzed for possible future developments |
| type: invalid | The issue is rejected (not an actual issue or not relevant) | The issue has been rejected because it is an unverifiable indication or the result of misunderstandings or not relevant to the project, so it will be closed and ignored |