opendev/infra-manual
Code Issues Proposed changes

Add terminology notes to README

Browse Source 
To try to get us on the same page about project and repository.

Change-Id: I47e902d7425ebab4814195cead1e041ee06b4ce5
This commit is contained in:
James E. Blair 2015-08-07 10:31:33 -07:00
parent f741b87b51
commit 1f4fc3ace2
1 changed files with 35 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
README.rst
View File

@ -1,9 +1,44 @@
=======================================
OpenStack Project Infrastructure Manual
=======================================
To build the manual, execute the following command::
$ tox
After running ``tox``, the documentation will be available for viewing
in HTML format in the ``doc/build/`` directory.
Terminology
===========
A note on terminology use in the manual:
This is a manual that describes how to use the OpenStack project
infrastructure. The OpenStack project, and the Technical Committee
(TC) in particular, from time to time uses words such as "project",
"team", "program", "repository", etc. to help classify how it
organizes the OpenStack project from an administrative point of view.
This manual is in service of OpenStack, but does so primarily by
documenting how developers and project drivers can use the
infrastructure to accomplish their work. While the TC may change its
terms from time to time, it is not necessary for us to change all of
the terminology in this manual to match. We should strive for
consistent terminology that matches what developers and our tooling
use. When we describe specific TC-related processes, we should use
the current TC terminology to avoid confusion.
Generally speaking these terms should be used as follows:
Project: The overall idea that there is a bunch of people working on a
bunch of code/text/etc. It can also refer to that actual collection
of code/text/etc (for instance, a project can be bundled up into a
tarball, and extracted into a directory). When a tool interacts with
that collection of code/text/etc, it interacts with the project (even
if it does so via the mechanism of git).
Repository: There are times when one needs to refer to the actual
source code management system of a project, that is, "git", and the
actual technical implementations of that SCM. In those cases where it
is important to distinguish the actual attributes of the SCM from the
project, it is useful to use the word "repository".