diff --git a/README.md b/README.md index c810fce..6a466f5 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,37 @@ # Keylime Enhancement Tracking and Backlog -The enhancement process has been in implemented to provide a way to review and assess the impact(s) of significant changes to Keylime. This in turn eases the management of our roadmap and release planning. +The enhancement process has been implemented to provide a way to review and +assess the impact(s) of significant changes to Keylime. This in turn eases the +management of our roadmap and release planning. -The Keylime Enhancement Tracking and Backlog process is loosely based on the [Kubernetes Enhance Proposal system](https://github.com/kubernetes/enhancements/tree/master/keps) +The Keylime Enhancement Tracking and Backlog process is loosely based on the +[Kubernetes Enhance Proposal system](https://github.com/kubernetes/enhancements/tree/master/keps) -This repo contains issues that map to enhancements that drive change requests targeted for Keylime and it's ecosystem. These enhancements are umbrellas for new features to be added to Keylime. An enhancement may take multiple releases to complete and be planned accordingly. +This repo contains +[issues](https://github.com/keylime/enhancements/issues?q=is%3Aissue+is%3Aopen) +that map to enhancements proposals. The proposals themselves are made in the +form of documents that describe the proposed modifications. This setup drives +the suggested changes to Keylime and its ecosystem. One should consider these +enhancements as umbrellas for new features to be added to Keylime. An +enhancement may take multiple releases to complete and be planned accordingly. -To view accepted enhancements under current development view with the [in-progress label](https://github.com/keylime/enhancements/issues?q=is%3Aissue+is%3Aopen+label%3Ain-progress) +To view accepted enhancements under current development view with the +[in-progress label](https://github.com/keylime/enhancements/issues?q=is%3Aissue+is%3Aopen+label%3Ain-progress) -To view enhancements under review, view with the [backlog label](https://github.com/keylime/enhancements/issues?q=is%3Aissue+is%3Aopen+label%3Abacklog) +To view enhancements under review, view with the [backlog +label](https://github.com/keylime/enhancements/issues?q=is%3Aissue+is%3Aopen+label%3Abacklog) ## Is My Thing an Enhancement? -We are trying to figure out the exact shape of an enhancement. Until then here are a few rough heuristics. +We are trying to figure out the exact shape of an enhancement. Until then here +are a few rough heuristics. An enhancement is anything that: - requires significant effort or changes to Keylime in a significant way -- impacts the operation of Keylime substantially such that engineers using Keylime will need retraining -- users will notice and come to rely on it. +- impacts the operation of Keylime substantially, such that engineers using + Keylime will need retraining +- users will notice and come to rely on It is unlikely an enhancement if it is: - fixing a test / bug @@ -26,21 +39,28 @@ It is unlikely an enhancement if it is: - performance / security improvements - adding error messages or events -If you are not sure, please ask within a keylime issue, the gitter channel or +If you are not sure, please ask within a Keylime issue, the gitter channel or the mailing list. ## When to Create a New Enhancement Create an issue here once you: - have circulated your idea to see if there is interest (for example on the - keylime mailing list or gitter community channel) + Keylime mailing list or gitter community channel) - (optional) have done a prototype in your own fork - are ready to be the project-manager for the enhancement ## Why are Enhancements Tracked -Once users adopt an enhancement, they expect to use it for an extended period of time. Therefore, we hold new enhancements to a high standard of conceptual integrity and require consistency with other parts of the system, thorough testing, and complete -documentation. As the project grows no single person can track whether all those requirements are met. The development of an enhancement often spans three stages: Alpha, Beta, and Stable; Enhancement Tracking Issues provide a checklist that allows for different approver's for different aspects, and ensures that nothing is forgotten across the development lifetime of an enhancement. +Once users adopt an enhancement, they expect to use it for an extended period of +time. Therefore, we hold new enhancements to a high standard of conceptual +integrity and require consistency with other parts of the system, thorough +testing, and complete documentation. As the project grows no single person can +track whether all those requirements are met. The development of an enhancement +often spans three stages: Alpha, Beta, and Stable; Enhancement Tracking Issues +provide a checklist that allows for different approver's for different aspects, +and ensures that nothing is forgotten across the development lifetime of an +enhancement. ## When to Comment on an Enhancement Issue @@ -54,26 +74,37 @@ Please do not comment on the enhancement issue to: ## How to create an enhancement -Create an issue in keylime/enhancements and then make a pull request to keylime/enhancements (using the available template). The issue is then used to map to the pull request, track the enhancement in the project board and map it to a planned milestone release. The pull request to keylime/enhancements is to allow community review and approve the enhancement. +Create an issue in keylime/enhancements and then make a pull request to +keylime/enhancements (using the available template). The issue is then used to +map to the pull request, track the enhancement in the project board and map it +to a planned milestone release. The pull request to keylime/enhancements is to +allow community review and approve the enhancement. -You may make your pull request as a [Draft Pull Request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) and then change it to a regular pull request when its ready for review. +You may make your pull request as a [Draft Pull +Request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request) +and then change it to a regular pull request when its ready for review. -New enhancements are labelled as 'backlog' +New enhancements are labelled as +[backlog](https://github.com/keylime/enhancements/issues?q=is%3Aissue+is%3Aopen+label%3Abacklog). -Once the pull request is approved and then merged it is labelled as 'in-progress' +Once the pull request is approved and then merged it is labelled as +[in-progress](https://github.com/keylime/enhancements/issues?q=is%3Aissue+is%3Aopen+label%3Ain-progress) and work is expected to start (this is not to say you cannot pre stage work into your own fork first). When you then make pull requests to any given Keylime repository, please reference the enhancement issue in your commit message (e.g. `#353`, you can also reference -the issue number when discussing a topic in any of the keylime repositories). For example +the issue number when discussing a topic in any of the Keylime repositories). For example someone may make a change which is going to have a possible impact upon an enhancement labelled as in 'backlog' or 'in-progress'. -Once the feature is delivered (the "Release Signoff Checklist" is completed) and all -pull requests are merged, with a planned and agreed release (TODO) then the 'complete' +Once the feature is delivered (the "Release Signoff Checklist" is completed) and +all pull requests are merged, with a planned and agreed release (TODO) then the +[complete](https://github.com/keylime/enhancements/issues?q=is%3Aissue+label%3Acomplete) label can be applied. ## I want to raise an issue around the enhancements process -Sure, go ahead. Please use `[Admin]` in the subject field of the issue and ensure it will then be tagged as `house-keeping`. +Sure, go ahead. Please use `[Admin]` in the subject field of the issue and +ensure it will then be tagged as +[house-keeping](https://github.com/keylime/enhancements/issues?q=is%3Aissue+is%3Aopen+label%3Ahouse-keeping).