infra-specs/specs/neutral-governance-website.rst

This work is licensed under a Creative Commons Attribution 3.0
Unported License.
http://creativecommons.org/licenses/by/3.0/legalcode

Neutral governance website

https://storyboard.openstack.org/#!/story/2000738

The governance.openstack.org website was initially created to publish Technical Committee governance documents. However since then it is also used to publish User committee documents (under /uc) and election details (under /election). Those are not very discoverable and the layout makes the UC look like a second-class citizen. This change proposes to put the Technical Committee documents under /tc, to mimic what is done with the other sections. The index page for governance.openstack.org would become a neutral page generally explaining governance and pointing to the various subsites. Proper redirects would be put in place to avoid breaking existing links.

Problem Description

See above.

Proposed Change

Like for all things OpenStack, the proposed solution is to create a new repository (openstack/governance-website) which would only be used to hold the neutral top page. openstack/governance publication jobs would be altered to publish under /tc, and redirects would be put in place to avoid breaking links.

Alternatives

We could put the neutral index page directly in the openstack/governance repository, and move all the Technical Committee content under a tc/ subdirectory within it.

The benefits would be that we'd avoid creating a repository for a single index page. The drawbacks are:

1. this would introduce a disrupting change to the governance repository directory structure, which we would have to propagate to documentation
2. the overall Sphinx title ("OpenStack technical Committee") would appear on the "neutral" index page, making it look not that neutral
3. it would make one repository more special than the others

Implementation

Assignee(s)

Primary assignee:

Thierry Carrez (ttx)

Gerrit Topic

We will use the neutral_governance as the gerrit topic.

Work Items

1. Create a openstack/governance-website repository
2. Push initial structure and proposed neutral page to the new repository
3. Switch publishing of openstack/governance to /srv/static/tc (in jenkins/jobs/projects.yaml) and wait for/trigger one refresh
4. Temporarily set governance.openstack.org/ docroot to /srv/static/tc (in modules/openstack_project/manifests/static.pp)
5. Set up a redirect from /tc/ to /srv/static/tc, while still using it as docroot (in modules/openstack_project/manifests/static.pp)
6. Publish openstack/governance-website content under /srv/static/governance (modify jenkins/jobs/projects.yaml and zuul/layout.yaml)
7. Alter ./modules/openstack_project/templates/static-governance.vhost.erb so that it supports a list of local redirects
8. Set up such redirects for /reference/ -> /tc/reference/, /resolutions/ -> /tc/resolutions/, and /goals/ -> /tc/goals in modules/openstack_project/manifests/static.pp
9. Set /srv/static/governance back as governance.openstack.org docroot in modules/openstack_project/manifests/static.pp

Repositories

openstack/governance-website

Servers

No new servers, this leverages static.openstack.org.

DNS Entries

No new entry, this leverages governance.openstack.org.

Documentation

I believe that this spec and changes to system-config and project-config repos will be enough documentation.

Security

I do not expect any new security concerns.

Testing

I don't believe that this spec introduces any infra specific testing.

Dependencies

None outside of this spec.