Define processes for proposing OpenWhisk enhancements (#4818)
Adds the first POEM which itself defines POEM - a process for proposing OpenWhisk enhancements.
diff --git a/.github/ISSUE_TEMPLATE/proposal.md b/.github/ISSUE_TEMPLATE/proposal.md
new file mode 100644
index 0000000..51906ab
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/proposal.md
@@ -0,0 +1,7 @@
+## Enhancement Description
+Please summarize your proposal (e.g. the "what", the "why", and some of the "how").
+
+* Proposal: [a link to the corresponding pull request if it exists already]()
+
+## References
+Please provide links to prior discussion (e.g., Apache `dev` list), wikis, or related issues.
diff --git a/proposals/POEM-1-proposal-for-openwhisk-enhancements.md b/proposals/POEM-1-proposal-for-openwhisk-enhancements.md
new file mode 100644
index 0000000..7cdcf00
--- /dev/null
+++ b/proposals/POEM-1-proposal-for-openwhisk-enhancements.md
@@ -0,0 +1,65 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+# Title
+Process for introducing an OpenWhisk Enhancement (POEM)
+
+## Status
+* Current state: Draft
+* Author: @style95
+
+## Summary
+
+Introduce and document a process for suggesting and implementing a substantive OpenWhisk Enhancement (POEM).
+A developer or group of developers working together to propose and implement a major new feature or functionality, a new subsystem, or a breaking change should follow the process described herein and open a proposal for consideration under this directory.
+
+## Motivation
+
+As the project grows, more and more issues are getting complex and require multiple parties and an extended period of time to develop them.
+We can incubate, manage, and elaborate new ideas in OpenWhisk with a standard way and a well-tracked artifact.
+The goals are to enhance the discoverability of proposals, and to help community members who want to get involved in the project.
+
+## Proposed changes
+
+### Procedures
+1. Create a pull request to describe your proposal with [this template](./POEM-N-template.md). The initial state of a proposal should be _"Draft"_.
+2. [Create a corresponding issue]((../../../issues/new?template=proposal.md)) to propose a new change based on [this template](../github/ISSUE_TEMPLATE/proposal.md). It is mainly used to track discussion history.
+3. Discuss the proposals using to form a consensus and update your proposal based on comments as needed. It is important to be inclusive, and to notify the OpenWhisk community of meaningful changes using the Apache [`dev` list](https://openwhisk.apache.org/community.html) for this project. Other forms of communication such as Slack are OK but any meaningful results should be documented in issues and the `dev` list.
+4. When members form a rough consensus for the proposal. The proposal owner can request a vote via the dev mailing list.
+5. The voting process follows the [Apache Voting guideline](https://www.apache.org/foundation/voting.html). The PR can be merged with the _"In-progress"_ state if the voting is successfully closed without any veto.
+6. The implementation begins as the proposal is filed into the repo and any volunteer can join the implementation ideally.
+7. If the proposal is not accepted or no consensus is formed, the PR is merged with the state, _"Abandoned"_.
+8. The proposal state is changed to "Completed"_ and any corresponding issues are closed once the implementation is compete, and the code is merged into the master branch.
+
+### Note
+* Committers and the PMC are supposed to label issues with an appropriate label to track issue and pull request status.
+* There are 4 labels(`draft`, `in-progress`, `completed`, and `abandoned`) to specify the state of a proposal and one special label (`proposal`) to differentiate proposals from other issues.
+
+### Proposal Lifecycle
+A proposal may be in one of the following states:
+* **Draft**: A new enhancement is proposed and it is under discussion.
+* **In-progress**: A consensus for the proposal is formed and implementation is in progress.
+* **Completed**: Implementation is finished and the change is included in the master branch.
+* **Abandoned**: A proposal is not accepted for some reason such as ”no consensus is formed”.
+
+## Issue
+
+Abandoned proposals are filed in this directory for archival.
+This is to keep and track all proposals at any stage in one place.
+A new idea can be derived from the abandoned one.
diff --git a/proposals/POEM-N-template.md b/proposals/POEM-N-template.md
new file mode 100644
index 0000000..31a24de
--- /dev/null
+++ b/proposals/POEM-N-template.md
@@ -0,0 +1,58 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+This is a template for a filed proposal.
+Create a pull request using this template.
+
+# Title
+This is the title of the POEM.
+A good simple title would help to describe the purpose of a proposal.
+# Your Poem
+
+Roses are red.
+Violets are blue.
+Your ideas are beautiful.
+We welcome you.
+## Status
+* Current state: (Draft | In-progress | Completed | Abandoned)
+* Author(s): @author (Github ID)
+
+## Summary and Motivation
+
+This section summarize the proposal.
+A brief description, proposed changes, and effects are expected to be included.
+You should cover the "what" and the "why" and briefly the "how".
+
+## Proposed changes: Architecture Diagram (optional), and Design
+This section may include large subsections, diagrams, links to references, and so on.
+
+It is recommended to include an architectural diagram.
+A link to an external resource is enough.
+
+### Implementation details
+
+This section describe how to implement the proposal.
+
+## Issue (optional)
+
+Any issue(compatibility, drawbacks, etc) should be describe here.
+
+## Integration and Migration plan (optional)
+
+If a proposal contains any breaking changes, it is required to include a plan for integration and migration.
diff --git a/proposals/README.md b/proposals/README.md
new file mode 100644
index 0000000..0c3b57a
--- /dev/null
+++ b/proposals/README.md
@@ -0,0 +1,40 @@
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+# How to submit a Proposal for an OpenWhisk Enhancement (POEM)
+
+This directory contains Proposals for OpenWhisk Enhancements (POEM). Proposed changes, new features and ideas are documented using a process outlined in this document. If you're a contributor interested in out of the proposals, you are encouraged to reach out to the proposal authors. This is a welcoming community and we look forward to your contributions.
+This directory contains approved proposals. The one who wants to include any major new feature, subsystem, piece of functionality and any breaking changes is supposed to open a proposal.
+
+You can find the full details in [POEM-1](./POEM-1-proposal-for-openwhisk-enhancements.md).
+
+## Quickstart to propose a new change.
+1. Copy the [POEM template](./POEM-N-template.md) and open a pull request.
+2. [Create a corresponding issue](/issues/new?template=proposal.md) with the prefix, `[Proposal]` in the title.
+3. Follow the process outlined in the [POEM-1](./POEM-1-proposal-for-openwhisk-enhancements.md).
+
+## When should I open a proposal?
+Create an issue when you propose:
+ * any major new feature, subsystem, or piece of functionality
+ * a big change which requires multiple PRs to complete it
+ * a breaking change that impacts public interfaces, data structures, or core execution paths.
+
+If you are not sure, ask to committers or the [PMC] of OpenWhisk.
+
+The POEM process was inspired by KEP( Kubernetes Enhancement Proposals), KIP (Kafka Improvement Proposal), and Cordova-discuss.
