... | ... | @@ -2,72 +2,79 @@ |
|
|
|
|
|
[[_TOC_]]
|
|
|
|
|
|
*(Updated 16 April 2021 for review)*
|
|
|
*(Updated 1 July 2021*)
|
|
|
|
|
|
Following the [Phased Proposal](https://gitlab.coko.foundation/ncbi/ncbi/-/wikis/Project-overview/Items-for-dev#update-23-march-2021) (submitted 9 March 2021) the DDWG agreed to include a formalised sign-off process to the current way of working.
|
|
|
The [Phased Proposal](https://gitlab.coko.foundation/ncbi/ncbi/-/wikis/Project-overview/Items-for-dev#update-23-march-2021) (submitted 9 March 2021) is no longer valid, an updated proposal following the provided use case epics is in progress.
|
|
|
|
|
|
## Pre-development sign-off process
|
|
|
## Use case epics
|
|
|
|
|
|
### Use case deliverables
|
|
|
The epic diagrams, provided by NCBI project owner (Stacy) in April 2021 describle NCBI's business uses cases. They include mitigations for a Phase 1 release that excludes supporting users with roles: Data Supplier and Investigator (aka Awardee).
|
|
|
|
|
|
These high-level deliverables were provided by NCBI project owner (Stacy).
|
|
|
The epics are organised into four [top-level categories](https://gitlab.coko.foundation/groups/ncbi/-/epics?label_name%5B%5D=top-level+epic):
|
|
|
|
|
|
1. Use case deliverable 1: Support for Word and XML chapter-processed content: Issue #450
|
|
|
2. Use case deliverable 2: Support for XML and PDF book-processed content: Issue #451
|
|
|
3. Use case deliverable 3: Permissions, Notifications, and Feature Improvements: Issue #452
|
|
|
4. Use case deliverable 4: Production-ready BCMS for internal staff users, Word authoring teams, PDF2XML vendors, and Bookshelf participant administrators: Issue #453
|
|
|
1. [Bookshelf Set up](https://gitlab.coko.foundation/groups/ncbi/-/epics/4)
|
|
|
2. [Pipeline Integration](https://gitlab.coko.foundation/groups/ncbi/-/epics/6)
|
|
|
3. [Submitter or Editorial team actions](https://gitlab.coko.foundation/groups/ncbi/-/epics/5)
|
|
|
4. [PDF2XML Vendor actions](https://gitlab.coko.foundation/groups/ncbi/-/epics/20)
|
|
|
|
|
|
Coko Project Manager (Dione) maps the existing issues for Phase 1 to each deliverable.
|
|
|
In phase 1 the priority must always be to develop the simplest implementation to meet these use cases, especially the ability to process content in all workflows and allow data migration.
|
|
|
|
|
|
### Per issue sign-off criteria
|
|
|
## Scoping development
|
|
|
|
|
|
Following Stacy's review of the mapped issues, the sign-off criteria are confirmed and agreed on for each issue. These my vary depending on the nature of the issue. When new or significantly adapted UIs are required, a visual walk-though, using roughs designs or demos of development-in-progress, is part of the sign-off process.
|
|
|
All issues (features and bugs) for scoping are on the [Backlog board](https://gitlab.coko.foundation/ncbi/ncbi/-/boards/605)
|
|
|
|
|
|
#### Sign-off responsibility
|
|
|
### The **Scoping phases**:
|
|
|
|
|
|
1. Backlog →
|
|
|
2. Research (requirements and implementation approach) →
|
|
|
3. Review (Check issue meets epic use case and write sign-off criteria) →
|
|
|
4. Approval (In queue for NCBI sign-off) →
|
|
|
5. Weight → (Dev team estimate before work can begin)
|
|
|
|
|
|
#### Per issue approval
|
|
|
|
|
|
* Sign-off criteria my vary depending on the nature of the issue. When new or significantly adapted UIs are required, a visual walk-though, using roughs designs or demos of development-in-progress, is part of the sign-off process.
|
|
|
* Stacy signs off user stories and their designs
|
|
|
* Evgeny or Martin sign off technical specs for integration-related issues
|
|
|
* Dione confirms the sign-off criteria are complete and sufficiently detailed for the developers to proceed.
|
|
|
* In cases where NCBI and Coko teams do not agree on the acceptance criteria, these issues should be floated to the DDWG to resolve together.
|
|
|
|
|
|
In cases where NCBI and Coko teams do not agree on the acceptance criteria, these issues should be floated to the DDWG to resolve together.
|
|
|
|
|
|
### Sign-off issues in-progress
|
|
|
#### Issue weighting
|
|
|
|
|
|
These issues can be found on the [Scoping Board](https://gitlab.coko.foundation/ncbi/ncbi/-/boards/605)
|
|
|
| Weight | Description |
|
|
|
| ------ | ------ |
|
|
|
| 1 | The simplest possible change. We are confident there will be no side effects. |
|
|
|
| 2 | A simple change (minimal code changes), where we understand all of the requirements. |
|
|
|
| 3 | A simple change, but the code footprint is bigger (e.g. lots of different files, or tests effected). The requirements are clear. |
|
|
|
| 5 | A more complex change that will impact multiple areas of the codebase, there may also be some refactoring involved. Requirements are understood but you feel there are likely to be some gaps along the way. |
|
|
|
| 8 | A complex change, that will involve much of the codebase or will require lots of input from others to determine the requirements.
|
|
|
| 13| A significant change that may have dependencies (other teams or third-parties) and we likely still don't understand all of the requirements. It's unlikely we would commit to this in a milestone, and the preference would be to further clarify requirements and/or break in to smaller Issues. |
|
|
|
|
|
|
* Scoping: issues that are being scoped
|
|
|
* Sign-off criteria review: issues ready for NCBI review and sign-off
|
|
|
* Sign-off criteria approved: Sign-off responsibility complete
|
|
|
*([Credit to Gitlab](https://about.gitlab.com/handbook/engineering/development/growth/#estimation))*
|
|
|
|
|
|
### Change requests and new feature requirements
|
|
|
#### Scope change after weighting
|
|
|
|
|
|
When changes are requested after the sign-off criteria have been approved, the Gitlab issue should document an estimate of the development time/effort required, as well as any other impacts the changes may have on the schedule. Change requests should only be accepted if they are critical to the priority of Phase 1, namely: the content processing workflow. The same applies to any new feature requests that may arise during Phase 1 development.
|
|
|
When changes are requested after approval, the issue is weighted again and any other impacts on the schedule are documented. Change requests should only be accepted if they are critical to Phase 1.
|
|
|
|
|
|
## Development workflow
|
|
|
## Development
|
|
|
|
|
|
These issues can be found on the [Development Board](https://gitlab.coko.foundation/ncbi/ncbi/-/boards/324)
|
|
|
All issues ready for development are on the [Development Board](https://gitlab.coko.foundation/ncbi/ncbi/-/boards/324)
|
|
|
|
|
|
Development begins on the issue when the relevant cycle starts (See [Project Schedule](https://gitlab.coko.foundation/ncbi/ncbi/-/wikis/Project-overview/project-schedule)). Dione may reschedule an issue if the sign-off criteria are not approved.
|
|
|
Development begins on the issue when the relevant cycle starts (See [Milestone](https://gitlab.coko.foundation/ncbi/ncbi/-/milestones)). Dione may reschedule an issue if the scope changes.
|
|
|
|
|
|
The **Development phases**:
|
|
|
|
|
|
1. Backlog feature with sign-off criteria approval →
|
|
|
2. Dev to do →
|
|
|
3. Dev Doing →
|
|
|
4. Blocked (when relevant) →
|
|
|
5. QA →
|
|
|
7. Internal review →
|
|
|
8. Dev Done
|
|
|
8. Closed issues (completed work that has been released and accepted by NCBI according to the sign-off criteria)
|
|
|
|
|
|
When dev issues are ready for NCBI's testing, Dione will create one issue listing all the relevant issues and documentation when relevant.
|
|
|
|
|
|
Be mindful of the information that the team needs to work with you on an issue and follow **best practices**, such as:
|
|
|
|
|
|
* Show your progress on issues by adding comments and including relevant commit numbers.
|
|
|
* When changing the status of your issues, make sure you add a comment that explains the status change. For example, if your issue status changes from 'doing' to 'blocked', the team will need to know why you are blocked so they can help.
|
|
|
Issues are added to the Dev board after scope approval and weighting.
|
|
|
|
|
|
1. Dev to do →
|
|
|
2. Dev Doing →
|
|
|
3. Dev Blocked (when relevant) →
|
|
|
4. Dev QA (assgined to @Sidorelauku) →
|
|
|
5. Dev QA fixes →
|
|
|
6. Dev Done →
|
|
|
7. Dev Dione QA (check on staging)
|
|
|
|
|
|
To avoid losing track of documents attached in closed Gitlab issues, save them in the Nextcloud 'NCBI\client-shared' folder for easy access.
|
|
|
Dev is 'done' when it its been tested and meets the sign-off criteria in the issue description.
|
|
|
|
|
|
#### How we manage branches:
|
|
|
|
... | ... | @@ -76,23 +83,25 @@ We have two main branches: |
|
|
* 'develop' - the code here is less stable than the master branch since it is work-in-progress. Tested code in this branch is merged into 'master' for client reviews.
|
|
|
* Each issue is developed and tested in its own branch before being merged into 'develop'.
|
|
|
|
|
|
## NCBI review
|
|
|
|
|
|
### Testing workflow
|
|
|
## Review and feedback
|
|
|
|
|
|
Dione provides **one testing handover issue** summarising dev work completed that is ready to test, including links to each relevant issue. Each issue is labelled with a release date for improved searching.
|
|
|
|
|
|
NCBI does testing according to the approved sign-off criteria.
|
|
|
NCBI does testing according to the sign-off criteria, summarised at the beginning of each issue.
|
|
|
|
|
|
If NCBI disagrees with a completed criteria, their testers untick the criteria and provide a link to a 'bug' issue (with clear steps to reproduce) as a comment in the issue. A ‘bug’ issue comprises some unexpected design or behaviour relevant to the sign-off criteria.
|
|
|
When providing feedback, please check the issues list for [features](https://gitlab.coko.foundation/ncbi/ncbi/-/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=feature) that haven't been developed yet or [bugs](https://gitlab.coko.foundation/ncbi/ncbi/-/issues?scope=all&utf8=%E2%9C%93&state=opened&label_name[]=bug) that are known. A ‘bug’ issue comprises some unexpected design or behaviour relevant to the sign-off criteria, and should include clear steps to reproduce the issue to avoid development delay.
|
|
|
|
|
|
When NCBI has completed testing against the sign-off criteria, Let Dione know in the testing handover issue.
|
|
|
|
|
|
Dione labels each issue as "Dev approved" and closes them.
|
|
|
|
|
|
|
|
|
### Testing agreements
|
|
|
|
|
|
#### NCBI review site
|
|
|
|
|
|
* The current ncbi.coko.foundation will move a new URL managed by our hosting partners to allow daily backups and migrations for each release.
|
|
|
* The site will be updated every Tuesday with whichever issues have been completed and merged.
|
|
|
* Dione will proovide release 'walk-thoughs' in the bimonthly review meeting when possible andf will continue to create a summary release issues.
|
|
|
|
|
|
#### For FTP submitted content
|
|
|
|
|
|
*Related issues #449 and #455*
|
... | ... | @@ -115,3 +124,5 @@ $ tree /am/ftp-private/bookshelf/coko/mockftp/ |
|
|
2. NCBI team will submit packages to all other folders. Corresponding Oragnizations exists in the BCMS, accessible at [NCBI's testing site](http://ncbi.coko.foundation) only. These orgs will remain stable in future update of your testing site so you can continue to use them.
|
|
|
3. Files for testing are maintained is a shared [Nextcloud folder](https://nextcloud.coko.foundation/s/zp26xmB3eP6Px3w) (password protected)
|
|
|
|
|
|
|
|
|
|