Issue Tracking

The new feature creation and bug reporting aspect of GridLAB-D™ are handled via the Issue tracking system in GitHub. Issues will also often be integrated into the GridLAB-D™ GitHub Projects Page to track a specific release or larger project context. This document will outline the expectations for creating and updating an Issue in the GitHub system, as well as the GridLAB-D™ expectations for how to progress Issues in the Project page.

Issues

The Issues page on GitHub allows the creation of specific "Issues", though Issues is a very broad term. These could be actual bugs or unexpected behavior, but can also be enhancements and proposed features, or just general maintenance tasks. For the GridLAB-D™ repository, "Issues" can be synonymous with "tickets", "tasks", or "requests". For any Issue submitted, it is important to include all relevant issue so the eventual assignee can understand the scope - this can be including a sample GridLAB-D™ file that replicates the behavior, steps to replicate the behavior, or details on an expected behavior (if an announcement). General issues will get evaluated twice a month and assigned accordingly, though the response time may come down to availability of specific staff/contributors.

Issue Progress

Once assigned, Issues will be expected to be resolved in a timely manner, again subject to staff/contributor availability if outside a formally defined Project board. Periodic (weekly interval, ideally) updates within the Issue are expected to track progress once work to address the issue/feature has been started. Issues assigned, but untouched, by the next monthly assignment review will be re-evaluated for possible re-assignment or adjusted prioritization.

Closing Issues

The first step for closing an Issue is to provide a solution to the stated issue, either via software bugfix, documentation update, or combination thereof. Any Issue resolving an abnormal model behavior, creation of a new behavior, or odd corner case of the GridLAB-D™ core is expected to have a corresponding autotest or unit test created. Where appropriate, especially for new functions/features, documentation should be included as part of the process. All code changes, code additions, and documentation updates are expected to be submitted via a Pull Request on the GitHub page, adequately referencing the Issue number.

Once the submitted pull request has been reviewed, accepted, and merged into the appropriate branch, the original assignee will evaluate if the issue has been resolved or if subsequent actions are needed (documenting these in the Issue comments). If fully resolved, the Issue may be closed and any Issue-specific branches deleted (if the Pull Request did not already do this).

Project Page

The Project page on GitHub allows the creation of a project/task-specific board to track and coordinate the process of assigning, addressing, and completing issues for a specific project or task. If not created directly in the Project page, any issue can be assigned to the active and accessible Projects via the "Projects" setting on the right side of the specific Issue page.

Columns

The columns of the board are used to reflect the current state of the issue.

No Status

This is the default column for any Issues assigned to the Project tracker. These Issues still need to be evaluated. If the issue is relevant and will need to be addressed as part of the overall Project, it will be moved to the "Todo" column. It may also be assigned a responsible party at this step. if the issue is found to be unrelated to the project scope, the reviewing party will remove or reassign the project flag (the Issue remains open, but goes back into the general pool).

Todo

"Todo" represents items that have not been started, but are deemed of importance/relevance to the listed Project. "Todo" Issues will get assigned to a specific individual, with the expectation assigned issues will get started within two weeks. Once work begins on an assigned "Todo" Issue, that Issue should be moved to the "In Progress" column. Assignments will be performed by the periodic reviewer, or by self-assignment of a relevant developer.

In Progress

"In Progress" represents Issues that are currently being examined, debugged, and actively addressed. Weekly updates on the Issue status are expected by the assignee. For example, include a comment or have a detailed commit message on the relevant branch indicating what is being examined, what current difficulties are, and current progress in addressing the issue. Once an issue is fixed, the assignee is expected to verify all autotests and other relevant unit tests still pass. Where relevant, the assignee should create a new autotest or unit test to validate the fix (and flag if the issue resurfaces with later commits). Relevant documentation updates must also be complete. At that point, the Issue can be moved to the "In Review" column.

In Review

"In Review" represents items that are fixed and awaiting a review and/or merge back into the relevant parent branch (e.g., develop). An appropriate pull request is expected to exist, except in very specific situations (very minor code change). The assigned reviewer will attempt to complete the review within two weeks of the "In Review" status start. The review will consist of ensuring builds still properly occur, all autotests and unit tests still pass, that a specific autotest or unit test was created (and passes), any appropriate documentation updates are present, and that all code follow the appropriate style guide. If changes are needed, they will be documented in the Issue or Pull request and the Issue will be pushed back to the "In Progress" column. Once all tests and code review are complete and related pull requests have been merged, the issue can be moved to the "Done" column. The original assignee or the reviewer may also close the Issue at this point.

Done

"Done" represents issues that have been resolved, merged into the appropriate code base, and are closed/complete. The "Done" column is primarily a holding area in case Issues need to be reopened for the Project during later development, or to track overall progress on the Project for administrative check-ins.

Moving Through the Board Process

Transitions between the different columns/stages are outlined above. Generally, the transition criteria are: * "No Status" to "Todo" - the Issue is relevant to the overall Project and should be completed in the next few weeks * "Todo" to "In Progress" - the Issue has a developed assigned and work addressing the request/issue has begun * "In Progress" to "In Review" - a fix or update has been completed and passes all tests, culminating in a pull or merge request for review * "In Review" to "Done" - the Issue has been resolved, including all passes testing, style checked, and appropriate documentation complete

Maintenance

Issues will be periodically evaluated by one of the main Developers. Project-related issues should be evaluated at least once a week by the main Developer of the project, and generic (non-Project-specific) issues should be evaluated and assigned once every two weeks.