From 2b52672457bee506c751820c2b64ae4d8426b372 Mon Sep 17 00:00:00 2001 From: Sundar Nadathur Date: Wed, 11 Mar 2020 00:19:49 -0700 Subject: [PATCH] Update contributing.rst per Ussuri goal and guidelines. Please see: http://lists.openstack.org/pipermail/openstack-discuss/2020-March/013003.html Change-Id: I8f4b8b25a0478d372f44e3691142a2d03a8bd01b --- CONTRIBUTING.rst | 24 ++-- doc/source/contributor/contributing.rst | 181 +++++++----------------- 2 files changed, 70 insertions(+), 135 deletions(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 84ad0431..9d9fdc34 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -1,13 +1,19 @@ -If you would like to contribute to the development of OpenStack, you must -follow the steps in this page: +The source repository for this project can be found at: - https://docs.openstack.org/infra/manual/developers.html + https://opendev.org/openstack/cyborg -If you already have a good understanding of how the system works and your -OpenStack accounts are set up, you can skip to the development workflow -section of this documentation to learn how changes to OpenStack should be -submitted for review via the Gerrit tool: +Pull requests submitted through GitHub are not monitored. - https://docs.openstack.org/infra/manual/developers.html#development-workflow +To start contributing to OpenStack, follow the steps in the contribution guide +to set up and use Gerrit: -Pull requests submitted through GitHub will be ignored. + https://docs.openstack.org/contributors/code-and-documentation/quick-start.html + +Bugs should be filed on Storyboard: + + https://storyboard.openstack.org/#!/project/openstack/cyborg + +For more specific information about contributing to this repository, see the +Cyborg contributor guide: + + https://docs.openstack.org/cyborg/latest/contributor/contributing.html diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst index 6e7408c5..46cc22d8 100644 --- a/doc/source/contributor/contributing.rst +++ b/doc/source/contributor/contributing.rst @@ -1,145 +1,74 @@ -============ -Contributing -============ +============================ +So You Want to Contribute... +============================ -Contributions are most welcome! You must first create a -Launchpad account and `follow the instructions here `_ -to get started as a new OpenStack contributor. +For general information on contributing to OpenStack, please check out the +`contributor guide `_ to get started. +It covers all the basics that are common to all OpenStack projects: the +accounts you need, the basics of interacting with our Gerrit review system, +how we communicate as a community, etc. -Once you've signed the contributor license agreement and read through -the above documentation, add your public SSH key under the 'SSH Public Keys' -section of review.openstack.org_. +Below will cover the more project specific information you need to get started +with {{cookiecutter.service}}. -.. _review.openstack.org: https://review.openstack.org/#/settings/ +Communication +~~~~~~~~~~~~~ -You can view your public key using: +We use the #openstack-cyborg IRC channel. -:: +The weekly meetings happen in this channel. You can find the meeting times, +previous meeting logs and proposed meeting agendas at +`Cyborg Team Meeting Page +`_. - $ cat ~/.ssh/id_*.pub +Contacting the Core Team +~~~~~~~~~~~~~~~~~~~~~~~~ -Set your username and email for review.openstack.org: +The core reviewers of Cyborg and their emails are listed in +`Cyborg core team `_. -:: +New Feature Planning +~~~~~~~~~~~~~~~~~~~~ - $ git config --global user.email "example@example.com" - $ git config --global user.name "example" - $ git config --global --add gitreview.username "example" +To propose or plan new features, we add a new story in the +`Cyborg Storyboard +`_ +and/or propose a specification in the +`cyborg-specs `_ repository. -Next, Clone the github repository: +Task Tracking +~~~~~~~~~~~~~ -:: +We track our tasks in the `Cyborg Storyboard +`_. - $ git clone https://github.com/openstack/cyborg.git +If you're looking for some smaller, easier work item to pick up and get started +on, ask in the IRC meeting. -You need to have git-review in order to be able to submit patches using -the gerrit code review system. You can install it using: +Reporting a Bug +~~~~~~~~~~~~~~~ -:: +You found an issue and want to make sure we are aware of it? You can do so +by adding an entry in the `Cyborg Storyboard +`_ or raising +it in the IRC meeting. - $ sudo yum install git-review +Getting Your Patch Merged +~~~~~~~~~~~~~~~~~~~~~~~~~ -To set up your cloned repository to work with OpenStack Gerrit +To merge a patch, it must pass all voting Zuul checks and get two +2s from +core reviewers. We strive to avoid scenarios where one person from a company +or organization proposes a patch, and two other core reviewers from the +same organization approve it to get it merged. In other words, at least +one among the patch author and the two approving reviwers must be from +another organization. -:: +We are constantly striving to improve quality. Proposed patches must +generally have unit tests and/or functional tests that cover the changes, +and strive to improve code coverage. - $ git review -s - -It's useful to create a branch to do your work, name it something -related to the change you'd like to introduce. - -:: - - $ cd cyborg - $ git branch my_special_enhancement - $ git checkout !$ - -Make your changes and then commit them using the instructions -below. - -:: - - $ git add /path/to/files/changed - $ git commit - -Use a descriptive commit title followed by an empty space. -You should type a small justification of what you are -changing and why. - -Now you're ready to submit your changes for review: - -:: - - $ git review - - -If you want to make another patchset from the same commit you can -use the amend feature after further modification and saving. - -:: - - $ git add /path/to/files/changed - $ git commit --amend - $ git review - -If you want to submit a new patchset from a different location -(perhaps on a different machine or computer for example) you can -clone the Cyborg repo again (if it doesn't already exist) and then -use git review against your unique Change-ID: - -:: - - $ git review -d Change-Id - -Change-Id is the change id number as seen in Gerrit and will be -generated after your first successful submission. - -The above command downloads your patch onto a separate branch. You might -need to rebase your local branch with remote master before running it to -avoid merge conflicts when you resubmit the edited patch. To avoid this -go back to a "safe" commit using: - -:: - - $ git reset --hard commit-number - -Then, - -:: - - $ git fetch origin - -:: - - $ git rebase origin/master - -Make the changes on the branch that was setup by using the git review -d -(the name of the branch is along the lines of -review/username/branch_name/patchsetnumber). - -Add the files to git and commit your changes using, - -:: - - $ git commit --amend - -You can edit your commit message as well in the prompt shown upon -executing above command. - -Finally, push the patch for review using, - -:: - - $ git review - -Adding functionality --------------------- - -If you are adding new functionality to Cyborg please add testing for that -functionality and provide a detailed commit message outlining the goals of -your commit and how you achived them. - -If the functionality you wish to add doesn't fix in an existing part of the -Cyborg achitecture diagram drop by our team meetings to disscuss how it -could be implemented +Project Team Lead Duties +~~~~~~~~~~~~~~~~~~~~~~~~ +All common PTL duties are enumerated in the `PTL guide +`_.