Restructure documentation of CIP process

Detail CIRs and their relationship to CIPs.

Author: Mats-SX

CIP-PROCESS.adoc

@@ -4,3 +4,49 @@ ifdef::env-github,env-browser[:outfilesuffix: .adoc]
 
 Improvements to the Cypher query language are managed through documents describing each feature of the language.
 Such a document is called a _Cypher Improvement Proposal_, or _CIP_ for short.
+
+=== Cypher Improvement Requests (CIRs)
+
+Before a language feature or change is mature enough for a full CIP to be created, it may be requested through the creation of a _Cypher Improvement Request_, or _CIR_.
+A CIR is created by raising an issue to this GitHub repository, which follows some conventions:
+
+* The title should be a summary of the proposed change
+* The issue should have a heading following this naming scheme:
+** `CIR-{YYYY}-{number}`, where `{YYYY}` is the current year (four numbers) and `{number}` is the number of the GitHub issue (this may be edited in after creation of the issue to get the number correct).
+
+A CIR is intended to be a light-weight document for requirements gathering, and does not need to fully consider all details of the proposal initially.
+This will be explored as the CIR develops and more people join the discussion.
+
+==== Lifecycle
+
+During the lifetime of a CIR, it may change in nature.
+It is preferable to keep the top post of the CIR updated with recent discussions, to allow new readers to easily get an updated view on what the CIR reflects, rather than have to scroll through a large history of change.
+
+The ultimate goal of a CIR is to spawn the creation (and subsequent acceptance) of one or more CIPs.
+
+=== Cypher Improvement Proposals (CIPs)
+
+Proposals for improving the Cypher query language should take the form of a CIP.
+A CIP is represented as a pull request against this repository, proposing the addition of a document following a few conventions:
+
+* The name of the document should be on the form `CIP{year}-{month}-{day}-{name}.adoc`.
+** The `{name}` part of the filename is a very short name of the proposed change; for instance the keyword the proposal intends to add or modify.
+If the "`{name}`" part contains multiple words, each word should be written using lower case characters, separated by a dash.
+** The date portion of the name is the the initial date of proposing the CIP (typically the same date as the submission of the pull request).
+* The document should be based on the CIP template document, to ensure a consistent structure with respect to other CIPs.
+* If the CIP is based on one or more CIRs, these should be explicitly referenced in the document and the pull request message.
+
+CIPs that additionally come with a reference implementation are very much appreciated, as is helps clarify the workings of the proposed improvement.
+This would help make the handling of the proposal quicker, or perhaps even make it more likely to be accepted.
+
+Suggestions and ideas are also welcome and much appreciated; these would best be submitted as "issues" in this repository on GitHub.
+The expectation is that these would eventually result in a CIP being created.
+
+==== Lifecycle
+
+Typically, CIPs spawn from one or more CIRs.
+A direct submission of a CIP is appropriate if the proposed changed is in the form of a concrete proposal.
+By starting from a CIR, you will be able to judge how large the general interest for the feature is before you embark on writing the CIP.
+Starting from a CIR also facilitates building an "experts group" that can work with you on the details of the proposal.
+
+Once a CIP has been issued, it will enter a phase of review, eventually becoming either accepted (and the pull request merged) or rejected.

README.adoc

@@ -5,7 +5,7 @@ ifdef::env-github,env-browser[:outfilesuffix: .adoc]
 image:https://travis-ci.org/opencypher/openCypher.svg?branch=master["Build Status", link="https://travis-ci.org/opencypher/openCypher"]
 
 This repository holds the specification of Cypher, the declarative property graph database query language.
-Its purpose is to be central to the process of evolving the specification of the language that is Cypher.
+Its purpose is to be central to the process of evolving the specification and standardisation of Cypher as a graph query language.
 
 * https://github.com/opencypher/openCypher/issues?q=is%3Aissue+is%3Aopen+label%3ACIR[Open Cypher Improvement Requests]
 * https://github.com/opencypher/openCypher/pulls?q=is%3Apr+is%3Aopen+label%3ACIP[Open Cypher Improvement Proposals]
@@ -18,6 +18,8 @@ It is our aim to make the process of specifying and evolving the Cypher property
 While we aim for the process to be open, this does not mean a public democracy, as all decisions are currently made by the Cypher Language Group (CLG).
 That said, we are of course extremely grateful for comments and suggestions on how to improve the Cypher query language.
 
+Refer to the link:CIP-PROCESS.adoc[Cypher Improvement Process] document for more details on CIPs, CIRs, their structure and lifecycle.
+
 === The Cypher Language Group
 
 The Cypher Language Group consists of:
@@ -33,36 +35,6 @@ Petra additionally acts as secretary for the group, calling meetings and ensurin
 
 Cypher was originally created by https://github.com/systay[Andrés Taylor].
 
-=== Improvement Proposals
-
-Ultimately, proposals for improving the Cypher query language should take the form of a _Cypher Improvement Proposal (CIP)_.
-These should typically be proposed as pull requests against this repository, proposing the addition of a document following a naming scheme of `CIP{year}-{month}-{day}-{name}.asciidoc`.
-The "`{name}`" part of the filename is a very short name of the proposed changed; for instance the keyword the proposal intends to add or modify.
-If the "`{name}`" part contains multiple words, each word should be written using lower case characters, separated by a dash.
-The date portion of the name is the the initial date of proposing the CIP (typically the same date as the submission of the pull request).
-
-CIPs that additionally come with a reference implementation are very much appreciated, as is helps clarify the workings of the proposed improvement.
-This would help make the handling of the proposal quicker, or perhaps even make it more likely to be accepted.
-
-Suggestions and ideas are also welcome and much appreciated; these would best be submitted as "issues" in this repository on GitHub.
-The expectation is that these would eventually result in a CIP being created.
-
-==== What is a CIP?
-
-A _Cypher Improvement Proposal_, or _CIP_ for short, is a document that details a change to Cypher.
-
-
-==== The life cycle of a CIP
-
-Proposing a change to Cypher starts by either submitting a CIP as a pull request to this repository, or by submitting a feature request.
-A direct submission of a CIP is appropriate if the proposed changed is in the form of a concrete proposal.
-A feature request is typically the preferred method of starting a proposal.
-By starting from a feature request, you will be able to judge how large the general interest for the feature is before you embark on writing the CIP.
-Starting from a feature request also facilitates building an "experts group" that can work with you on the details of the proposal.
-
-The comment thread on the GitHub issue for the feature proposal is an excellent place for discussing ideas
-
-
 === Meeting notes
 
 The Cypher Language Group published meeting notes from all the group meetings at https://opencypher.github.io/meeting-minutes/