From 61eaf9ba6c5f573b9b71ba36f99a11d6ae287468 Mon Sep 17 00:00:00 2001 From: Jesse White Date: Mon, 15 Apr 2019 11:38:38 -0400 Subject: [PATCH] Documentation updates. --- DEVEL.md | 2 ++ LICENSE.md | 4 +-- PLUGINS.md | 76 ------------------------------------------------------ README.md | 22 ++++++++++------ 4 files changed, 18 insertions(+), 86 deletions(-) delete mode 100644 PLUGINS.md diff --git a/DEVEL.md b/DEVEL.md index 3af85fb3..edebf9d3 100644 --- a/DEVEL.md +++ b/DEVEL.md @@ -4,3 +4,5 @@ * All interfaces in the 'api' module should contain the version in which they were introduced using a `@since` tag in the interface's Javadoc * Interfaces which are expected to be exposed in the OSGi registry by the API users should be annotated with the `org.opennms.integration.api.v1.annotations.Exposable` annotation * Interfaces which are expected to be consumed from the OSGi registry by the API users should be annotated with the `org.opennms.integration.api.v1.annotations.Consumable` annotation +* Interfaces which have associated builder implementations in the common module should be annotated with the 'org.opennms.integration.api.v1.annotations.Model' annotation + diff --git a/LICENSE.md b/LICENSE.md index 0ad75ad4..0cca88b1 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -3,8 +3,8 @@ OpenNMS License This file is part of OpenNMS(R). -Copyright (C) 2018 The OpenNMS Group, Inc. -OpenNMS(R) is Copyright (C) 1999-2018 The OpenNMS Group, Inc. +Copyright (C) 2019 The OpenNMS Group, Inc. +OpenNMS(R) is Copyright (C) 1999-2019 The OpenNMS Group, Inc. OpenNMS(R) is a registered trademark of The OpenNMS Group, Inc. diff --git a/PLUGINS.md b/PLUGINS.md deleted file mode 100644 index 381a089d..00000000 --- a/PLUGINS.md +++ /dev/null @@ -1,76 +0,0 @@ -# Plugins - -This API layer should make it easier to write and maintain plugins outside of OpenNMS. - -For example these plugins could: - * Extend the event configuration - * Implement a new detector/monitor/collector,ticketer etc... - -## Proposed Workflow (WIP) - -1) We would host some new .m2 repositories - one for snaps, one for releases - * release contains TOG and contributed plugins - * snapshots contain latest artifacts for projects managed by the TOG - * contributed plugins must be reviewed before we publish them to the repositories we manage - * these contain binary code which in the same process and with the same permissions as the OpenNMS,Minion & Sentinel JVMs -2) Ship OpenNMS with our new repos in `etc/org.ops4j.pax.url.mvn.cfg `: -``` -org.ops4j.pax.url.mvn.repositories= \ - http://new.opennms.org/maven2@id=central, \ - https://snaps.opennms.org/content/repositories/snapshots@id=opennms.snapshots.deploy@snapshots@noreleases -``` -3) Users create a new project from a template: - * `mvn archetype generate a project` - * input githuborg githubid projectname? -4) Edit the project - * drop in some event configuration - * implement a monitor - * see - ### Things we should be able to expose - * depend on other plugins - * depend on other features using Karaf the karaf feature definitions -5) Compile and install: - * mvn install - * mvn integration-test - * how can we help verify that it actually works? -6) To try locally: -``` -[OpenNMS,Sentinel,Minion] - admin@opennms> feature:install opennms-plugin-githuborg-githubid-projectname -``` -7) When installed: - * bundles interact with the `opennms-api [>=v1.1.5,<2.0.0], [>=2.0.0,<3.0.0]` - * expose config, expose plugins i.e. monitors - * consume facts, callbacks, etc... -8) To share with others: - * Push to GH - * Tag - * Open PR against: opennms-plugins - * PR include GH repo info - * GPG signature of release - git hash ain't enough - * Team reviews for sanity & security, make the release - * On release: - * Clone, build, and push to .m2 repository - * Tweet -9) To find and install: - * Website generated by plugin metadata - * API endpoint for other UIs - * Download plugin as .tgz for offline - * what happens when the plugin depends on other plugins - include them in a larger artifact? - * Plugins contain documentation & links which are added to the website - * `admin@opennms> feature:repo-refresh` - * `admin@opennms> feature:list opennms-plugin-*` - * `admin@opennms> feature:install opennms-plugin-who-what` -10) Validate that the runtime requirements for the plugin we met: - * `admin@opennms> health:check` -11) Use feature X: - * how can I access documentation about the feature I just installed? -12) Make sure feature X stays installed after a clean boot: - * `admin@opennms> plugin:enable opennms-plugin-who-what` -13) Allow users to license their plugins - use existing license management - * Split archetypes between those that do and don't need license management? We want to keep the artifacts as lean as possible. -14) To help keep plugins up-to-date, we can implements both API version X and X+1 simulatneously in a few releases, giving people a chance to migrate before we drop 1.x. - * Horizon supports major versions for M months - * Meridian supports major version for Y years -15) To audit - * Keep track of # hits on artifacts - * Expose list of installed plugins via opt-in data choices diff --git a/README.md b/README.md index 8c9e1d30..3696c135 100644 --- a/README.md +++ b/README.md @@ -3,9 +3,10 @@ This project aims to make it easier to write plugins and extensions to OpenNMS by introducing a stable interface against which these can be written. Versions of OpenNMS and Meridian will then implement at least one major version of the API. -This API is designed to follow [Semantic Versioning](https://semver.org/). +## Features -## Current Support +Users for the API can currently take advantage of the following features and interfaces. +See the interfaces defined in the `api` module for a complete list. ### Extend @@ -15,7 +16,7 @@ This API is designed to follow [Semantic Versioning](https://semver.org/). ### Consume * Runtime information - * Version - major,minor,patch,snapshot? + * Version - major,minor,patch,snapshot * Container type - OpenNMS vs Minion vs Sentinel * Alarm lifecycle callbacks * DAOs @@ -35,10 +36,15 @@ This API is designed to follow [Semantic Versioning](https://semver.org/). * Provisiond detectors * Ticketers -## Bucket List -### Add support for exposing +## Versioning + +Given that the API is fairly new, we expect that we will need to make changes and improvements over the next few releases of OpenNMS Horizon. +In order to make sure that your plugins or extensions do not break within minor and patch releases: + + * Do not implement, or extend interfaces marked with the `@Consumable` annotation as we reserve the right to add new method signatures to these. + * Do not implement, or extend interfaces marked with the `@Model` annotation as we reserve the right to add new method signatures to these. + * Use the provided builders for these interfaces in the `common` module instead. + +Once stabilized, we are aimign to follow [Semantic Versioning](https://semver.org/). - * Topology provider - * Notification strategy - * Time Series Persistence strategy