Reference doc for new language additions

This patch adds a reference document explaining the process for adding a
new language to the OpenStack ecosystem. Early discussions of the
content in this patch happened in a ML thread[0].

[0] http://lists.openstack.org/pipermail/openstack-dev/2016-November/106877.html

Change-Id: I7202b619dae60facf27eff35f5e99e018c01858c

reference/index.rst

@@ -12,6 +12,7 @@ Reference documents which need to be revised over time.
    charter
    projects/index
    new-projects-requirements
+   new-language-requirements
    licensing
    service-project-naming
    project-testing-interface

reference/new-language-requirements.rst

@@ -0,0 +1,177 @@
+.. NOTE(flaper87): This document sets the bar high on purpose. The idea is to
+   list all the possible things that may be needed/useful when adding a new
+   language and reduce it. I'd like this cleaning process to happen during the
+   review of the document. Therefore, before it lands.
+
+=================================================================
+ Requirements for language additions to the OpenStack Ecosystem
+=================================================================
+
+Adding new programming languages in OpenStack is possible by following the
+process described below. Every new language addition goes through careful
+consideration on both, technical and community, aspects. When considering a new
+programming language addition, the community must consider whether this language
+may or may not fragment the community, what the impact is on the infrastructure
+team and systems, how this language impacts the release model, etc.
+
+Innovation is highly encouraged. However, teams experimenting with new languages
+should keep under consideration the points mentioned above and the process
+explained in this document. New programming languages in OpenStack are added
+under specific circumstances where the existing, already accepted, languages
+have been proven to not meet the technical requirements and the concerns
+at the point evaluation.
+
+.. NOTE(flaper87): Is the 2-steps process good or just too complex? I like it
+   because it allows for separating discussions (which was a problem in previous
+   proposals) and it also allows for organizing the work. Teams should not worry
+   about doing any of the up-front work until phase 1 is over. Once phase1 is
+   passed, teams can work on addressing the requirements and move their projects
+   forward in parallel.
+
+   Other processes that would allow for some separation like the one I mentioned
+   above are worth evaluating too.
+
+The process for adding a new language consists of two separate steps that
+require some work up-front. The first step involves the analysis of the need for
+a new language and the second one the support for the new language in the
+OpenStack ecosystem.
+
+After reviewing and agreeing on the need for a new language, the team driving
+this effort should start working on the second phase. The needs of a new
+language should not be questioned during the evaluation of the second phase,
+unless the team working on it decides the language is not needed anymore.
+
+Step 1: Use case analysis
+#########################
+
+The TC will evaluate the use case for the new proposed language in this phase.
+Members of the community interested in this addition are expected to have
+started a discussion on the mailing list before presenting the request to the
+TC. It's encouraged to let the mailing list discussion mature before it's
+brought to the TC.
+
+The discussion should evolve around the needs of the language, the technical
+difficulties at hand and the reasons why existing languages are not good enough
+for the task. Adding a new language should not be the norm and it comes with a
+cost, as explained earlier in this document. Projects should strive for
+consuming the existing languages in the ecosystem.
+
+Once the discussion has matured, the request should be brought up to the TC for
+further discussion, evaluation and voting in the form of :ref:`resolutions`.
+
+Step 2: Requirements evaluation
+###############################
+
+If the need of a new language is agreed on, the members interested in it are
+expected to work with the rest of the community on meeting the following minimum
+requirements:
+
+Setup the CI pipelines for the new language
+-------------------------------------------
+
+Work with the infrastructure team on setting up CI pipelines for projects using
+the new language. The following tasks should be addressed as part of this work:
+
+* CI jobs for lint checkers
+* CI jobs for unit tests
+* CI templates for functional tests
+* CI jobs for documentation builds
+* Ensure the jobs for meeting the :doc:`project-testing-interface`
+  requirements exist.
+* subunit-formatted output from tests
+* Provide a mechanism for pre-caching and/or mirroring dependencies in the gate
+* Provide plugins for DevStack to help creating QA and development environments
+
+Define how the deliverables are distributed
+-------------------------------------------
+
+Work with the release team to define the release processes for projects using
+the new programming language. These processes should answer the following
+questions:
+
+* Should the deliverables be shipped in binary format? or is the source code
+  enough?
+* How can the release of the new deliverables be automated?
+* Where should the deliverables be published? Is there a PyPi equivalent for the
+  new language?
+
+Define how stable maintenance will work
+---------------------------------------
+
+Work with the stable team to define the maintenance processes for stable
+branches. These processes should address the following requirements:
+
+* Backport policies (if new policies are needed)
+* CI jobs for stable branches
+* Identify main contacts for stable branches and jobs maintenance
+
+Define how internationalization will work
+-----------------------------------------
+
+Work with the i18n team to define the translation processes for projects using
+the new language. These processes should address the following requirements:
+
+* Provide tools and jobs for importing and exporting translations
+
+Define how documentation will work
+----------------------------------
+
+Work with the documentation team to define the processes for generating,
+publishing and maintaining the documentation for projects using the new
+language. All projects should use Sphinx for their project documentation and
+follow the api-ref_ standards for their API documentation, should they need one.
+The use of language specific tools for other type of documentation (developer's)
+is fine.
+
+* Provide tools and jobs for generating documentation
+* Adopt OpenStack's themes and documentation standards.
+
+.. _api-ref: http://developer.openstack.org/api-guide/quick-start/index.html
+
+Define how dependencies will be managed
+---------------------------------------
+
+Work with the infrastructure and requirements team to define a process for
+managing dependencies for the new language similar to the existing
+`requirements` process used for Python dependencies. This process should
+describe:
+
+* How the dependencies for the new language are consumed
+* How the dependencies for the new language can be managed, pinned, etc,
+  if necessary
+* How the dependencies' license will be tracked and reviewed
+* How testing-specific dependencies can be managed
+* How to track reproducible builds
+
+Define a way to share code/libraries for projects using the language
+--------------------------------------------------------------------
+
+Work with the Oslo team to define the processes for sharing common code among
+projects using the new language. These processes should answer the following
+questions:
+
+* What team owns the shared code? Should this code fall under the Oslo team
+  umbrella?
+* How are the produced libraries going to be delivered?
+* How are the produced libraries going to be consumed?
+
+Guarantee compatible functionality for the base common libraries
+----------------------------------------------------------------
+
+Most OpenStack projects rely on a set of base common libraries that provide a
+seamless experience to operators and users of OpenStack. Any new language must
+provide a compatible behavior with these libraries either by developing a
+counterpart version of the library in the language or proving that the language
+itself (or any existing library) is capable of guaranteeing compatibility.
+
+The following libraries have an impact on the operator's and user's experience,
+therefore their behavior is considered critical and it must be guaranteed by any
+new language:
+
+* oslo.config
+* oslo.log
+
+Once the above requirements have been addressed, a final resolution should be
+brought up to the TC. This resolution will mark the language as an official
+language in the ecosystem. The language can be used by other projects from this
+moment on.

resolutions/index.rst

@@ -1,3 +1,5 @@
+.. _resolutions:
+
 =============
  Resolutions
 =============