# For organizing NotaryProject

## Objective
1. Make it easier for community to see the roadmap and progress
2. Make it easier for contibutors to take up issues and help with PRs
3. Make planning easier to predict the cadence of the releases

## Our challanges

### Specfication & Code releases in tandem
There is dependency across the specfication and code, and ideally specification should exist before code is released

### Split across multiple repository
When things are split across multple repo, managing the project is harder using just the native GitHub tools. Other communities have reported problems with multiple repository project management in GitHub as well. Examples below

https://softwareengineering.stackexchange.com/questions/378094/effective-project-management-spanning-multiple-repos-in-github

https://ops.tips/blog/managing-multiple-github-repositories/

#### Is there mitigation for multiple repository problem?
Yes, but multiple repo projects use external tools from code tree or perfoce to manage. Examples below. However these are paid tools

https://codetree.com/guides/managing-issues-across-multiple-github-repositories

https://www.perforce.com/blog/vcs/managing-multiple-git-repositories

## Given the challanges what is the suggestion

### For project management
1. We have one top level "Github project" at the main "NotaryProject/" level, and one sub project at each of the repo levels.
2. We use the same "labels" and "milestones" tags in all the repos, and then can use the top level project to filter across all repos by using those labels.
3. Follow some best practices
- Always create an issue, and not just a PR.
- For every issue we create the issue has to manually linked to the local repository specfic project( "MyRepoProject") and if we think this should also have visibilty to the aggregate level, then also mark it to the top Level project ("MilestonesAcrossAllRepos")
- Use appropriate labels for each kind of issue and PR. At a minimum each issue should be linked to a milestone. And when the milestone is not clear to the issue originator, they can leave it open for the maintainers to address
4. We regularly curate and verify the above rules are being followed

### For communicating roadmap
1. We use a combination of ROADMAP.MD and a static githib project with "ISSUES" in it to show the roadmap split across the milestones. The ROADMAP.MD is rarely updated. The benefit of having this other project is that we can link in the "issues" and "pr" of other repos.To use this, a new repo will be added, called "roadmap" in the notaryproject. This is the same communication paradigm used by "Github" for communicating their roadmap.

### For releases
At one point should only be marching towards one STABLE release, and all the milestones lead up to that STABLE release.

### For picking milestone names for the release we are working on
Suggest the following milestones for each "Stable" release that we are targeting.

| Releases |Milestone names | Release Purpose |
| -------- | -------- | -------- |
| Alpha | alpha-1, alpha-2,... | Not for production use. No backward compatabilty gurantee |
| Beta | beta-1, beta-2 | Not for production use. Backward comptabilty is best effort
| Release Candidate | RC-1, RC-2,...| These are the release candidates and only major bug fixes will be addressed, any one of these release candidate can become the final stable release|
| Stable | Not needed | This is the release community should refer to for developing additional tooling from specfication or using the provided library and CLI tools

The actual release name can follow a convention like https://github.com/notaryproject/notation/blob/7b30dc534f37e4f3922be97025d1e74c4145e30c/RELEASE_MANAGEMENT.md#release-management

### For picking label names
Besides the usual label names that Github provides, suggest we use the following, and then continue to monitor which other ones we need
***roadmap*** - This is to call out those issues that show up on roadmap. These issues may never have a linked PR, and will be closed once the roadmap item is delivered.
***spec*** - These will point to issues related to the specfication. These will have PR associated to them.

## Renmaing & Modifications to descriptions
1. Rename “notation” repository to “notation-go-cli”, and modify its description to state that it is based on “notaryV2” specfication
2. Rename “notaryproject” repository to “notaryV2”
3. Should we rename or add description to the “notary” repo to call it “notaryV1”