Maintenance plan creation

[manicprogrammer]

A plan for how to maintain the map(s) under this project must be created.

Without a proper maintenance plan including instructions on how to contribute via a PR the maps under this project will go out of date and become untrustworthy. Though the maps are not meant to be a definitive source, their general timeliness and broad reflection of the state of the ecosystem are important to their utility.

[manicprogrammer]

Some initial thoughts meant only to capture the thoughts for potential use in the plan are:

1. A schedule for review for each core element type. This is ideally done using the advantages of version control diffs to minimize change efforts. Most if not all the core type have their document under version control.
2. Include in the element data for each type the last date of review- this will then show in kumu.io map when drilling into the element and might be able to be used as a filter on the map itself
3. Include in the element data for each type the version control repo URL and populate this field for the core type

[manicprogrammer]

PR#20 merged in the repo URL field populated for core elements.
Last date of review for each element to be reviewed was intentionally left out as it would require touching the element record when reviewed even when there were no changes to its connection. That would be a bad design for maintainability, versioning and deploy.

[manicprogrammer]

As part of the maintenance plan have decided to add a field to the elements data:

• Spec Last Reviewed Date

The field date should represent the date that a spec was reviewed for any changes in the element data or connections from the element. ONLY element data has this field, not connection data, since only element data represents the specification artifacts.

Every time the spec is reviewed for updates the Spec Last Reviewed Date will be updated to the date of the review.
As only core type elements should have dependencies or references only core type element spec documents will be reviewed and have this field updated.

The use of the new field will cause an update to the element data when the spec is reviewed even if there were no changes to the element information or connections. This will not require a new release. The update to that field in the data could sit in the repo for an indefinite period of time before a functional change causes a release. This lack of a release on every element field change for the Spec Last Reviewed Date can mean there is a significant difference between what the kumu map shows for the last date of review and when the last date of review actually occurred thus limiting the value of the field. It will be left to the details of the maintenance plan to define a means to prevent too great of a differential. These approaches might include:

• manual update of the field in the kumu map for the element spec reviewed
• scheduled releases even if no functional change in order to propagate the review date values

An additional field named Element Last Modified Date was considered to allow for map users to see when the last actual change to an element or its connections was made but this has been shelved and can be added later if desired.

[manicprogrammer]

In experimenting with maintenance options on Dec. 30 I reviewed many of the core specifications, updated the last reviewed date in version control, did not do a formal release but did manually update the Last Reviewed Date field in the kumu map for the appropriate elements. There were no updates to the map from the review process otherwise.

The review on each specification was performed by comparing the main branch of the repo for the specification for differentials since the last review date and looking for impacting changes. If some specifications had extensive changes that precluded a straightforward diff between version control commits then the specification review was deferred. The deferral was to allow for the specification to be re-analyzed and re-read in it's output document format to evaluate for any changes. The deferral was only because the time allotted on Dec. 30. did not support the more detailed reading review of any that needed it.