# NotaryV2 & Notation - Releases and Milestones

## Purpose
To ensure alignment and transparency, following are the things we need to work on
1. Agree on a release process/methodolgy under which releases will be made available for the wider community
2. Agree on a roadmap process/methology to communicate the plans in advance of release and solicit feedback
3. Create a draft roadmap

## Overview

This document proposes both a release process and a roadmap process by which the collective effort of Notary V2 Working group can be provided for consumption and perusal to the wider community who are focussed on the end-to-end container image signing use case.

---

## 1. Notation release process/methodolgy Proposal
The document proposes, a simple model of three release aliases - Last(Released), Current(In-Progress), Next (Planned). The releases can be referred by their specfic release names (Refer the next section on release names) or the alias. At anytime, an alias will point to just one specfic relase. Each release will have a purpose, scope, audience , release notes, binaries.

### Current Status of Releases

| Release Alias | Release Name | ETA Date | Notes |
| ----------------- | --------------- | -------- | -------- |
| Last/Released | N/A | N/A | No release has been made till date |
| Current/In-Progress| Alpha or RC1 | Oct'21 | -------- |
| Next/Planned | Beta or RC2 | TBD | -------- |

### Release names
Refer : https://github.com/notaryproject/notation/blob/7b30dc534f37e4f3922be97025d1e74c4145e30c/RELEASE_MANAGEMENT.md#release-management

### What makes up a release
Each release will consist of the following items that together will constitute a release

1. Release Notes - The release notes will provide information in a human readable format. Refer next section for the outline of a release notes template and an example
2. Content - This referes to the actual content of the release. For Notation client it's a binary. For notaryproject, it would be specs (.md files)binary of notation client.
2.1 Software Binary - Of th Notation client, available in one or more packaging formats that can be readily used alongside other container clients
2.2 Software Source Code - References to one or more specfic source code repositories from which the binaries are built
2.3 Documents - These consist of one or more documents, including Notary V2 specfications and user guides, that provide instructions on how to use the Software Binary

### Release Notes Template
The release notes will contain the following sections.
1. Goal of the release
2. List of feature/capabilties added with this release
3. List of fixed issued (as compared to the previous release)
4. List of known open issues (aka Errata, with workarounds where applicable)
5. Information on whethr the new release is backwards compatabilty with what all prior releases or not.
Refer a good example to follow at https://github.com/open-policy-agent/gatekeeper/releases/tag/v3.4.0

### Release Readiness Review
Each release will go through a readiness reviews, against a checklist of items before a decision is made to release it or not. Overrides to any of the checklist items must be documented and consented on.
1. Published release notes
2. Meeting the stated goal of the release ( any deviations must be recorded in release notes)
3. No known security issues that can jeopradize data or application security
4. Adherence to test plan. 100% pass rate. Any exceptions should be documented and agreed before release. Features related to the failing test cases may be pulled or not communicated as available.

## 2. Notation Roadmap process/methodology proposal
1. Lets use [GitHub "project boards"](https://docs.github.com/en/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards) tools for roadmap planning and project management.
2. Propose we use two project boards, one for "High-level roadmap" and the other for each release.
4. The "High-level roadmap" project board is
- [ ] Curated every X weeks, and its contents are not automatically moved;
- [ ] The maintainers and/or release managers will adjust this roadmap and document the reason for the changes
- [ ] This roadmap will define "Epics" (aka Major Product areas), which will be linked to actual "Features". The "Features" will automatically move through "release" projects
- [ ] This High Level roadmap will use "Issues" or "Notes" to represent items
5. The "Release" project board will automatically stays up-to-date with the information on GitHub. When a pull request or issue changes, this project reflects that change.
- [ ] The Release will be accompanied by a "Release Checlist", that will be reviewed as part of the release readiness review.
- [ ] The project roadmap will use "Issues" or "Pull Requests" to track the progress

## Roadmap Templates and Legend
Many of the concepts here are borrowed from the [GitHub roadmap](https://github.com/github/roadmap) methodolgy , the following is recommendation for Notation sub project under Notary V2

### Guide to the roadmap

Every item on the roadmap is an issue, with a label that indicates each of the following:
* A release phase that describes the next expected phase of the roadmap item. See below for a guide to release phases.
* A feature area that indicates the area of the product to which the item belongs. For a list of current product areas, see below.
* Once a feature is delivered, the shipped label will be applied to the roadmap issue and the issue will be closed with a comment linking to the relevant Changelog post.

### Release phases
Release phases indicate the stages that the product or feature goes through, from early testing to general availability.

**alpha**: Primarily for early testing and feedback
Features still under heavy development, and subject to change. Not recommended for production use. Limited and/or preliminary documentation and test cases.

**beta**: Publicly available in full or limited capacity
Features nearing completion and documentation going through review. Test cases formalization starts but not complete.

**ga**: Generally available to all customers
Ready for production use.

Some of our features may still be in the exploratory stages, and have no timeframe available. These are included in the roadmap only for early feedback. These are marked as follows:

**in design**:
Feature in discovery phase. We have decided to build this feature, but are still figuring out how.

**exploring**:
Feature under consideration. We are considering building this feature, and gathering feedback on it.

### Roadmap stages
The roadmap is arranged on a project board to give a sense for how far out each item is on the horizon. Every product area or feature is added to a particular project board column according to the milestones expected to ship next. Be sure to read the disclaimer below since the roadmap is subject to change, especially further out on the roadmap. You'll also find an Exploratory column, which is used in conjunction with the in design and exploring release phase labels for when no timeframe is yet available.

Another suggestion is the creation of a ROADMAP.md and the maintainers selectively pull items from that list into projects/milestones. Here is an example - https://github.com/openservicemesh/osm/blob/main/ROADMAP.md

### Product & Feature Areas
The following is a list of proposed product/epic areas, with their sub features called out in each of them. These product/epic areas will likely spead over multiples releases, and withing each product/epic area there will be individual features. While a product/epic area will span multiple releases, a feature will not span across multiple releases. So features need to be granular and split in smaller chunks to fit in individual releases.

***Signing & Verification Specfication***: All aspects related to generating and verifying signature specfication.

| # | Feature/Workflow Description | Specification for first GA Release | Notation Client API & CLI for first GA Release | Additonal Information |
| ---- | ------------------------------------------- | --------| --------- |-----|
| 1 | [Signature Format](https://hackmd.io/Vz_tGRvGTL6Spmdpv8QulA?view) (JWS, PKCS7) | Must | Must | Start with JWS for the first Alpha release, but move to PKCS7 for first GA release |
| 2 | Extensible for additional Signature Formats | Must | Future | Must have the spec ready and extensibilty at first release. Notation implementation can come later |
| 3 | Additional Signature Format (DSSE) | Future | Future | DSSE is not ready yet |
| 4 | Signature Payload Format | Must | Must | |
| 5 | Signature Mainifest Format | Must | Must | |
| 6 | Signature Expiry | Must | Must | |
| 7 | Certificate Expiry | Must | Must | |
| 8 | TSA Signature | Must | ?? | Good prerequiste for Revocation |
| 9 | Multiple Signature Generation/Storing | Must | Must | |
|10 | Multiple Signature Validation | Future | Future | |
|11 | Revocation of Signatures | Must | Future | Signatures formats & Validations shall not change when revocation support is added; Will standard and flexible PKI constructs for it|
|12 | Revocation of Certificates | Must | Future | This shall also cover revocation of keys. Revocaion of Signatures should cover revocation of individual artifacts |
|13 | Customer defined Signature Verification Policies (SVP) without Scoping | Must | Must | Scoping is in reference to narrowing the signature verification to certain registries/repos/namespaces |
|14 | Customer defined SVP with Scoping | Nice | Nice | There are good uses cases here for it. We need to document those|
|15 | Customer defined SVP for mixed signed & unsigned usage | Must | Must | "SVP without Scoping" feature should cover this use case. Called out here for completness. Useful in migration scenarios |
|16 | Uer defined Signed MetaData | Must | Must | Allows customized signature envelope fields. TODO: Need to add some use cases in Signature Format section |
|17 | Add Certificate in Trust Stores | Must | Must | TODO: Steve/Samir document some scenarios. Explains how PKI Hiearchy and flexibilty can be used to address varied needs|
|18 | Signing & Verifying artifacts besides images| Must | Must | No incremental development is foreseen for this. Perhaps new test cases |
|19 | Tag Signing | Future | Future | There is mitigation for this use case as Tags can be resolved to image digests. Customer Expereince does not change; Offers differnt security gurantees |

***Notation Library***: Actual SDK code that is written for use, and includes the Notation CLI
The above table already captures the specfications which need to be incorporated in the Notation Client. Besides the above, the following need to handled for the first release
1. APIs & CLI for Signing with Keys/Certificates on local host (This is likely for test and development use only)
2. APIs & CLI for Interfacing Notation with PKCS 11 supported signing services.

***Docker CLI***: Integrating with Docker Clients as plugin or a native feature
1. Plugin for Docker CLI. This is must have for the first GA release to give a better CX for customer using Docker Clients.
2. Native Integration with Docker. This is a nice to have for the first GA release

***Documentation***: This is for any kind of end user facing documentation such as release notes and user guides
1. Blog post to convey the directional intent of Notary V2 after we have split in sub projects and what customers can expect
2. Release notes for each Release
3. User Guide for Notation CLI
4. Curating online documentation on Github to fix inconsistencies

***Orchestrators Integration***: Integrating with Kubernetes or other Orchestrators for Verification
While Orchetration integration is outside the scope of Notary V2, we must have atleast one of these mechanism in place at release time. These could be their own library or open source package.
1. K8s Integration via OPA Gatekeeper using Rego
2. K8s Integration via OPA Gatekeeper using Webhooks
3. K8s Integration via https://sse-secure-systems.github.io/connaisseur/v2.0.0/
4. Others ???

***Distribution/Registry Specficatoin***: ORAS related work.
This is not an exhaustive/granular list.
1. Copying an Image should automatically include its signature

### Disclaimer
The forward-looking roadmap does not represent a commitment, guarantee, obligation or promise to deliver any product or feature, or to deliver any product and feature by any particular date, and is intended to outline the general development plans.

## 3. Create a Draft Roadmap
### Current State of Projects
There are multiple projects, so we need to consolidate the different projects we are tracking to where it makes sense, such as notation by itself

***Can we close one of these two?***
https://github.com/orgs/notaryproject/projects
* https://github.com/orgs/notaryproject/projects
* https://github.com/orgs/notaryproject/projects/1


***Can we just close these next two?***
https://github.com/notaryproject/notaryproject/projects
* https://github.com/notaryproject/notaryproject/projects/1
* https://github.com/notaryproject/notaryproject/projects/2


### Review Proposed Notation "High-Level Roadmap" concept

https://github.com/users/iamsamirzon/projects/2
https://github.com/users/iamsamirzon/projects/4

This is the focus of the meeting. Create high level "Notes" and then "Convert them later" into issues and Pull requests.

### Open Questions
1. Discussion on Test plans and Coverage
Need to ensure that adequate test plans and test cases are added

### Answered Questions
1. Should we use Milestones?
Milestones allow us to group Issues and Feature request, so intutively they make sense to map 1:1 ( 1 Milestone to one Release) or N:1 ( Mulitple Milestones to one Release). They are more widely undertood and used in the GitHub community than the existing project tool. As and when the new project tool ([currently in Beta](https://docs.github.com/en/issues/organizing-your-work-with-project-boards/managing-project-boards/about-project-boards)) becomes available, we can relook at

2. Can we create a draft roadmap?
Created and documented above in the section 2.