From f605d6e6ce3712dc425367a396218d291efbc3cc Mon Sep 17 00:00:00 2001 From: "James E. Blair" Date: Fri, 19 Sep 2014 19:28:44 -0700 Subject: [PATCH] Doc updates for project-config Change-Id: Idffa13d5d1990f47e46fc5b711563949da78b6f8 --- doc/source/custom_roles.py | 28 +++++++++++- doc/source/gerrit.rst | 2 +- doc/source/irc.rst | 5 +-- doc/source/jeepyb.rst | 28 ++++++------ doc/source/jjb.rst | 23 +++------- doc/source/nodepool.rst | 3 +- doc/source/running-your-own.rst | 2 + doc/source/stackforge.rst | 76 ++++++++++++++++----------------- doc/source/static.rst | 2 + doc/source/zuul.rst | 7 ++- 10 files changed, 93 insertions(+), 83 deletions(-) diff --git a/doc/source/custom_roles.py b/doc/source/custom_roles.py index e1df48d5f3..0905e0ad84 100644 --- a/doc/source/custom_roles.py +++ b/doc/source/custom_roles.py @@ -41,7 +41,32 @@ def file_role(name, rawtext, text, lineno, inliner, ref = ('https://git.openstack.org/cgit/openstack-infra/config/tree/%s' % text) - node = nodes.reference(rawtext, text, refuri=ref, **options) + linktext = 'config: %s' % text + node = nodes.reference(rawtext, linktext, refuri=ref, **options) + return [node], [] + + +def config_role(name, rawtext, text, lineno, inliner, + options={}, content=[]): + """Link a local path to a cgit file view. + + Returns 2 part tuple containing list of nodes to insert into the + document and a list of system messages. Both are allowed to be + empty. + + :param name: The role name used in the document. + :param rawtext: The entire markup snippet, with role. + :param text: The text marked with the role. + :param lineno: The line number where rawtext appears in the input. + :param inliner: The inliner instance that called us. + :param options: Directive options for customization. + :param content: The directive content for customization. + """ + + ref = ('https://git.openstack.org/cgit/openstack-infra/' + 'project-config/tree/%s' % text) + linktext = 'project-config: %s' % text + node = nodes.reference(rawtext, linktext, refuri=ref, **options) return [node], [] @@ -51,4 +76,5 @@ def setup(app): :param app: Sphinx application context. """ app.add_role('file', file_role) + app.add_role('config', config_role) return diff --git a/doc/source/gerrit.rst b/doc/source/gerrit.rst index dea9a23f84..caaea10844 100644 --- a/doc/source/gerrit.rst +++ b/doc/source/gerrit.rst @@ -25,7 +25,7 @@ At a Glance * :file:`modules/openstack_project/manifests/review_dev.pp` :Configuration: * :file:`modules/openstack_project/templates/review.projects.ini.erb` - * :file:`modules/openstack_project/files/review.projects.yaml` + * :config:`gerrit/projects.yaml` :Projects: * http://code.google.com/p/gerrit/ :Bugs: diff --git a/doc/source/irc.rst b/doc/source/irc.rst index 65dd839112..c988c1202f 100644 --- a/doc/source/irc.rst +++ b/doc/source/irc.rst @@ -22,7 +22,7 @@ At a Glance * :file:`modules/openstack_project/manifests/eavesdrop.pp` * :file:`modules/openstack_project/manifests/review.pp` :Configuration: - * :file:`modules/gerritbot/files/gerritbot_channel_config.yaml` + * :config:`gerritbot/channels.yaml` :Projects: * http://wiki.debian.org/MeetBot * http://sourceforge.net/projects/supybot/ @@ -189,8 +189,7 @@ Gerritbot watches the Gerrit event stream (using the "stream-events" Gerrit command) and announces events (such as patchset-created, or change-merged) to relevant IRC channels. -Gerritbot's configuration is in -:file:`modules/gerritbot/files/gerritbot_channel_config.yaml`. +Gerritbot's configuration is in :config:`gerritbot/channels.yaml` Teams can add their channel and go through the standard code review process to get the bot added to their channel. The configuration is organized by channel, diff --git a/doc/source/jeepyb.rst b/doc/source/jeepyb.rst index 3cd58db1e5..05fc0a24bb 100644 --- a/doc/source/jeepyb.rst +++ b/doc/source/jeepyb.rst @@ -21,7 +21,7 @@ At a Glance * :file:`modules/openstack_project/manifests/review_dev.pp` :Configuration: * :file:`modules/openstack_project/templates/review.projects.ini.erb` - * :file:`modules/openstack_project/files/review.projects.yaml` + * :config:`gerrit/projects.yaml` * :file:`modules/openstack_project/files/pypi-mirror.yaml` :Projects: * https://git.openstack.org/cgit/openstack-infra/jeepyb @@ -56,9 +56,8 @@ connect to things or how to operate is in has-downloads=False OpenStack Gerrit projects are configured in the -:file:`modules/openstack_project/files/review.projects.yaml`. -file. When this file is updated, ``manage-projects`` is run -automatically. +:config:`gerrit/projects.yaml`. file. When this file is updated, +``manage-projects`` is run automatically. #. Project definition:: @@ -70,20 +69,19 @@ automatically. has-wiki: True acl-config: /path/to/acl/file -The above config gives puppet and its related scripts enough information -to create new projects, but not enough to add access controls to each -project. To add access control you need to have an ``acl-config`` -option for the project in ``review.projects.yaml`` file. That option -should have a value that is a path to the ``project.config`` for that -project. +The above config gives puppet and its related scripts enough +information to create new projects, but not enough to add access +controls to each project. To add access control you need to have an +``acl-config`` option for the project in ``projects.yaml``. That +option should have a value that is a path to the ``project.config`` +for that project. That is the high level view of how we can configure projects using the pupppet repository. To create an actual change that does all of this for a single project you will want to do the following: -#. Add a - ``modules/openstack_project/files/gerrit/acls/project-name.config`` - file to the repo. The contents will probably end up looking like +#. Add a ``gerrit/acls/project-name.config`` file to the + ``project-config`` repo. The contents will probably end up looking like the block below (note that the sections are in alphabetical order and each indentation is 8 spaces):: @@ -102,8 +100,8 @@ a single project you will want to do the following: [submit] mergeContent = true -#. Add a project entry for the project in - ``modules/openstack_project/files/review.projects.yaml``.:: +#. Add a project entry for the project in ``gerrit/projects.yaml`` in + the ``project-config`` repo.:: - project: openstack/project-name acl-config: /home/gerrit2/acls/project-name.config diff --git a/doc/source/jjb.rst b/doc/source/jjb.rst index 7e96bd41b6..de91ed3201 100644 --- a/doc/source/jjb.rst +++ b/doc/source/jjb.rst @@ -17,7 +17,7 @@ At a Glance :Puppet: * :file:`modules/jenkins/manifests/job_builder.pp` :Configuration: - * :file:`modules/openstack_project/files/jenkins_job_builder/config/` + * :config:`jenkins/jobs/` :Projects: * https://git.openstack.org/cgit/openstack-infra/jenkins-job-builder :Bugs: @@ -28,7 +28,7 @@ At a Glance Overview ======== -In order to make the process of managing hundreds of Jenkins jobs +In order to make the process of managing thousands of Jenkins jobs easier, Jenkins Job Builder was designed to take YAML based configurations and convert those into jobs that are injected into Jenkins. @@ -40,9 +40,9 @@ Configuring Projects ==================== The YAML scripts to make this work are stored in the -:file:`modules/openstack_project/files/jenkins_job_builder/config/` -directory. In this directory you can have four different types of -yaml config files: +:config:`jenkins/jobs/` directory of the project-config repository. +In this directory you can have four different types of yaml config +files: * Jenkins Jobs Defaults in ``defaults.yaml``. * Jenkins Jobs Macros to give larger config sections meaningful names in @@ -64,19 +64,6 @@ Example defaults config: - defaults: name: global - description: | -

This job is managed by puppet and will be overwritten.

- -

Do not edit this job through the web

- -

If you would like to make changes to this job, please see: - - - https://git.openstack.org/cgit/openstack-infra/config - - - In modules/openstack_project/files/jenkins_jobs -

project-type: freestyle concurrent: true diff --git a/doc/source/nodepool.rst b/doc/source/nodepool.rst index 6f54a091a8..7fd342f521 100644 --- a/doc/source/nodepool.rst +++ b/doc/source/nodepool.rst @@ -19,7 +19,8 @@ At a Glance * :file:`modules/openstack_project/manifests/single_use_slave.pp` :Configuration: * :file:`modules/openstack_project/templates/nodepool/nodepool.yaml.erb` - * :file:`modules/openstack_project/files/nodepool/scripts/` + * :config:`nodepool/scripts/` + * :config:`nodepool/elements/` :Projects: * https://git.openstack.org/openstack-infra/nodepool :Bugs: diff --git a/doc/source/running-your-own.rst b/doc/source/running-your-own.rst index ac4e6e33b8..f5cfa8b937 100644 --- a/doc/source/running-your-own.rst +++ b/doc/source/running-your-own.rst @@ -2,6 +2,8 @@ .. _running-your-own: +.. warning:: Parts of this file are out of date + Running your own CI infrastructure ################################## diff --git a/doc/source/stackforge.rst b/doc/source/stackforge.rst index 382300ac5f..b65bb6f36c 100644 --- a/doc/source/stackforge.rst +++ b/doc/source/stackforge.rst @@ -46,15 +46,16 @@ Add a Project to StackForge Create a new StackForge Project with Puppet =========================================== -OpenStack uses Puppet and a management script to create Gerrit projects -with simple changes to the openstack-infra/config repository. To start make -sure you have cloned the openstack-infra/config repository -``git clone https://git.openstack.org/openstack-infra/config``. +OpenStack uses Puppet and a management script to create Gerrit +projects with simple changes to the openstack-infra/project-config +repository. To start make sure you have cloned the +openstack-infra/project-config repository ``git clone +https://git.openstack.org/openstack-infra/project-config``. -First you need to add your StackForge project to the master project list. -Edit ``modules/openstack_project/files/review.projects.yaml`` and add a -new section for your project in alphabetical order within the file. -It should look something like:: +First you need to add your StackForge project to the master project +list. Edit :config:`gerrit/projects.yaml` and add a new section for +your project in alphabetical order within the file. It should look +something like:: - project: stackforge/project-name description: Latest and greatest cloud stuff. @@ -72,8 +73,7 @@ unnecessary branches and tags after the merge requires an openstack-infra core member to do so. The next step is to add a Gerrit ACL config file. Edit -``modules/openstack_project/files/gerrit/acls/stackforge/project-name.config`` -and make it look like:: +``gerrit/acls/stackforge/project-name.config`` and make it look like:: [access "refs/heads/*"] abandon = group project-name-core @@ -108,15 +108,15 @@ these additional tools. Add Jenkins Jobs to StackForge Projects ======================================= -In the same openstack-infra/config repository (and in the same change -if you like) we need to edit additional files to setup Jenkins jobs -and Zuul for the new StackForge project. +In the same openstack-infra/project-config repository (and in the same +change if you like) we need to edit additional files to setup Jenkins +jobs and Zuul for the new StackForge project. If you are interested in using the standard python Jenkins jobs (docs, pep8, python 2.6 and 2.7 unittests, and coverage), edit -``modules/openstack_project/files/jenkins_job_builder/config/projects.yaml`` -and add a new section for your project in alphabetical order in the file. It -should look something like:: +:config:`jenkins/jobs/projects.yaml` and add a new section for your +project in alphabetical order in the file. It should look something +like:: - project: name: project-name @@ -127,10 +127,10 @@ should look something like:: - python-jobs List of jobs included to the ``python-jobs`` jobs group is located in -``modules/openstack_project/files/jenkins_job_builder/config/python-jobs.yaml``. -For document publication there's also a publisher job template for the -popular `Read the Docs`_ documentation hosting service, which can be -used by adding the ``hook-{name}-rtfd`` template to the jobs list:: +:config:`jenkins/jobs/python-jobs.yaml`. For document publication +there's also a publisher job template for the popular `Read the Docs`_ +documentation hosting service, which can be used by adding the +``hook-{name}-rtfd`` template to the jobs list:: - project: name: project-name @@ -147,10 +147,9 @@ If you aren't ready to run any gate tests or other project-specific jobs yet, you don't need to edit ``projects.yaml``. Now that we have Jenkins jobs we need to tell Zuul to run them when -appropriate. Edit -``modules/openstack_project/files/zuul/layout.yaml`` -and add a new section for your project in alphabetical order within the file. -It should look something like:: +appropriate. Edit :config:`zuul/layout.yaml` and add a new section for +your project in alphabetical order within the file. It should look +something like:: - name: stackforge/project-name template: @@ -159,17 +158,17 @@ It should look something like:: - name: python3-jobs If you aren't ready to run any gate tests yet and did not configure -python-jobs in projects.yaml, it should look like this instead:: +python-jobs in ``projects.yaml``, it should look like this instead:: - name: stackforge/project-name template: - name: merge-check - name: noop-jobs -That concludes the bare minimum openstack-infra/config changes necessary to -add a project to StackForge. You can commit these changes and submit -them to review.openstack.org at this point, or you can wait a little -longer and add your project to GerritBot first. +That concludes the bare minimum openstack-infra/project-config changes +necessary to add a project to StackForge. You can commit these changes +and submit them to review.openstack.org at this point, or you can wait +a little longer and add your project to GerritBot first. Request an Initial Gerrit Core Group Member =========================================== @@ -190,12 +189,10 @@ project group management. Configure StackForge Project to use GerritBot ============================================= -To have GerritBot send Gerrit events for your project to a Freenode IRC -channel edit -``modules/gerritbot/files/gerritbot_channel_config.yaml``. -If you want to configure GerritBot to leave alerts in a channel -GerritBot has always joined just add your project to the project list -for that channel:: +To have GerritBot send Gerrit events for your project to a Freenode +IRC channel edit :config:`gerritbot/channels.yaml`. If you want to +configure GerritBot to leave alerts in a channel GerritBot has always +joined just add your project to the project list for that channel:: stackforge-dev: events: @@ -223,11 +220,10 @@ end of this file that looks like:: - master If you are defining a new channel, add it also in -``modules/openstack_project/files/accessbot/channels.yaml`` file, optionally -defining also its mask. -The mask will be used to define the access level for IRC users who are not -listed in that file in the ``global`` section or otherwise listed for the -channel. +:config:`accessbot/channels.yaml` file, optionally defining also its +mask. The mask will be used to define the access level for IRC users +who are not listed in that file in the ``global`` section or otherwise +listed for the channel. For instance: diff --git a/doc/source/static.rst b/doc/source/static.rst index d25bb3ae6f..814d59d1ae 100644 --- a/doc/source/static.rst +++ b/doc/source/static.rst @@ -19,6 +19,8 @@ At a Glance * http://specs.openstack.org :Puppet: * :file:`modules/openstack_project/manifests/static.pp` +:Configuration: + * :config:`specs/index.html` :Projects: * http://apache.org/ :Bugs: diff --git a/doc/source/zuul.rst b/doc/source/zuul.rst index e4ad54bc4a..d38a7c150d 100644 --- a/doc/source/zuul.rst +++ b/doc/source/zuul.rst @@ -20,7 +20,7 @@ At a Glance * :file:`modules/openstack_project/manifests/zuul_prod.pp` * :file:`modules/openstack_project/manifests/zuul_dev.pp` :Configuration: - * :file:`modules/openstack_project/files/zuul/layout.yaml` + * :config:`zuul/layout.yaml` :Projects: * http://launchpad.net/zuul * https://git.openstack.org/cgit/openstack-infra/zuul @@ -78,9 +78,8 @@ each commit is correctly tested. Zuul's current status may be viewed at ``_. -Zuul's configuration is stored in -:file:`modules/openstack_project/files/zuul/layout.yaml`. Anyone may -propose a change to the configuration by editing that file and +Zuul's configuration is stored in :config:`zuul/layout.yaml`. Anyone +may propose a change to the configuration by editing that file and submitting the change to Gerrit for review. For the full syntax of Zuul's configuration file format, see the `Zuul