Tools for managing community goals.
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Zuul e052e18989 Merge "add an ocata-em report showing contributions by org and project" 1 month ago
burndown-generator Add initial tools for burndown charts 1 year ago
goal_tools Replace git:// URLs with https:// 2 months ago
queries add an ocata-em report showing contributions by org and project 1 month ago
tools Replace git:// URLs with https:// 2 months ago
.gitignore new command to build sql database directly from gerrit 5 months ago
.gitreview OpenDev Migration Patch 2 months ago
.stestr.conf set up stestr 1 year ago
.zuul.yaml add python 3.6 unit test job 10 months ago
README.rst Replace git:// URLs with https:// 2 months ago
requirements.txt add instructions about tracking status 10 months ago
setup.cfg Change openstack-dev to openstack-discuss 5 months ago add basic files for setting up a tox environment 1 year ago
test-requirements.txt set up stestr 1 year ago
tox.ini test python 3.6 by default 10 months ago


Community-wide Goal Tools

To use the tools, run tox -e venv --notest to create a virtualenv with all of the dependencies. The tools will then be installed into .tox/venv/bin and can be run directly from there or via tox -e venv -- COMMAND_NAME.


import-goal can be used to create stories, tasks, and boards in storyboard for tracking work on completing the goals.


who-helped is a tool for looking at the contributor statistics for a set of patches.



To set up a workspace to use the python3-first tools:

$ mkdir python3-first
$ cd python3-first
$ git clone
$ git clone
$ git clone
$ git clone
$ mkdir Output

Preparing Patches

Before preparing any patches for a team, make sure that all of the changes to modify the .gitreview file for the stable/rocky branches in the repositories have been merged. Failing to do this will mean some rocky branch changes will be proposed against master.

To prepare the patches for one team, use

$ cd goal-tools
$ ./tools/python3-first/ ../Output Documentation

The script will create a subdirectory in the output location using the team name, clone all of the repositories owned by the team, then process each one to create a patch for each branch that needs to have job settings imported.

It will also create a log file in the output directory called do_team.TIMESTAMP.log (where "TIMESTAMP" is replaced with a real timestamp. The log file should show all of the work done, including the diffs for all of the patches created.

$ ls -1 ../Output/Documentation/

Proposing Patches

BEFORE PROPOSING ANY PATCHES FOR A TEAM, talk to the PTL of that team via email or IRC to ensure they are ready to receive them.

Review the log file created by before proposing the patches to ensure that there are no extraneous changes (the YAML parser does not produce exactly the same format output as input, and we have seen a couple of cases where it introduces errors by changing the indentation level incorrectly).

Then use to submit the patches:

$ ./tools/python3-first/ ../Output Documentation

The script will provide a list of all of the patches to be proposed and a count, then wait for you to press <Return>. After you do, it will submit all of the patches to gerrit.

The project-config patch will trigger the script to create the patch to remove the settings from openstack-infra/project-config for all of the repos for a team. WILL NOT submit the patch, though, because we do not want it to accidentally be approved before the jobs are added in each repository. YOU SHOULD PROPOSE IT early and mark it as a work-in-progress by setting the Workflow flag to -1 so teams can use it while reviewing the other patches.

$ cd ../Output/Documentation/openstack-infra/project-config
$ git review

Marking the Team "In Progress"

  1. Assign yourself to the task from!/story/2002586 for the team you are working on and set the status to "Review".
  2. The Infrastructure team needs to know not to approve changes to job configurations for a team while the team's settings are being migrated. To inform them, send email to the list. The migration announce command will build a message body containing all of the repository names.:

    $ .tox/venv/bin/python3-first migration announce Oslo
    The Zuul project settings for the Oslo repositories
    has begun. Please do not approve any changes to
    openstack-infra/project-config/zuul.d/projects.yaml for
    the following repositories:
    - openstack-dev/cookiecutter
    - openstack-dev/oslo-cookiecutter
    - openstack-dev/pbr
    - openstack/automaton

    See for an example.

Marking the Team "Complete"

  1. Update the sign-up task from!/story/2002586 and set the status to "Merged".
  2. Reply to the preivous message on the openstack-infra mailing list to announce that the migration for the team is completed.


python3-first is the parent command for a set of tools for implementing the python3-first goal.

The jobs extract sub-command reads the Zuul configuration from the openstack/project-config repository and then for a given repository and branch prints the set of job definitions that should be copied into that branch of that project.

$ git clone
$ git clone
$ cd goal-tools
$ tox -e venv -- python3-first jobs extract --project-config ../project-config \
openstack-dev/devstack stable/queens

The jobs retain sub-command reads the same Zuul configuration data and prints the settings that need to stay in openstack/project-config.

$ tox -e venv -- python3-first jobs retain --project-config ../project-config \

The jobs update command will modify the zuul settings in a repository to include all of the settings shown by jobs extract.

$ git clone
$ cd oslo.config
$ git checkout -b python3-first
$ cd ../goal-tools
$ tox -e venv -- python3-first jobs update --project-config ../project-config \

The repos clone command will use the project governance data to find a list of all of the git repositories managed by a project team and then clone local copies of all of them. This makes it easier to work on all of the projects for a single team as a batch.

$ mkdir Oslo
$ cd goal-tools
$ tox -e venv -- python3-first repos clone ../Oslo Oslo

Use the -v option to python3-first to see debug information on stderr (allowing stdout to be redirected to a file safely).

There are several higher-level wrapper scripts for running these tools in tools/python3-first. takes as input a goal URL, a working directory and a team name. It clones all of the repositories owned by the team and prepares local branches with patches to import jobs into master and all of the relevant stable branches.

$ cd goal-tools
$ ./tools/python3-first/ ../Py3FirstGoalWork Documentation can be used to re-run one stage of the patch creation process for all of the repos and a single branch.

$ ./tools/python3-first/ ../Py3FirstGoalWork Documentation stable/rocky creates the branch and patch for a single repository.

$ ./tools/python3-first/ ../Py3FirstGoalWork/openstack/whereto stable/rocky

After all of the patches for a team are prepared locally, they can be submitted for review using

$ ./tools/python3-first/ ../Py3FirstGoalWork Documentation