From 78cce72f8a495dd7b2daf50623c60348fcb95adf Mon Sep 17 00:00:00 2001 From: Matthew Oliver Date: Tue, 12 May 2020 11:08:57 +1000 Subject: [PATCH] Ussuri contrib docs community goal This patch standardizes the CONTRIBUTING.rst file and adds the required doc/source/contributor/contributing.rst Swift already had a detailed CONTIRBUTING.rst and an informative REVIEW_GUIDELINES.rst in the root of the repo. So we are also pulling them into the contributor documentation so they can not only be easily found in the checked repo but in the online documentation. Change-Id: I4c84efbe50eb25ab922c9d6b69198dae341af48b --- CONTRIBUTING.rst | 10 +++ REVIEW_GUIDELINES.rst | 2 +- doc/source/contributor/contributing.rst | 79 ++++++++++++++++++++ doc/source/contributor/review_guidelines.rst | 1 + doc/source/index.rst | 9 +++ 5 files changed, 100 insertions(+), 1 deletion(-) create mode 100644 doc/source/contributor/contributing.rst create mode 100644 doc/source/contributor/review_guidelines.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 3aef4845f4..245843071b 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -21,6 +21,16 @@ Swift is nothing without the community behind it. We'd love to welcome you to our community. Come find us in #openstack-swift on freenode IRC or on the OpenStack dev mailing list. +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. + +If you want more Swift related project documentation make sure you checkout +the Swift developer (contributor) documentation at +https://docs.openstack.org/swift/latest/ + Filing a Bug ~~~~~~~~~~~~ diff --git a/REVIEW_GUIDELINES.rst b/REVIEW_GUIDELINES.rst index a61a298698..e2bc4c6bbb 100644 --- a/REVIEW_GUIDELINES.rst +++ b/REVIEW_GUIDELINES.rst @@ -369,7 +369,7 @@ Endeavor to leave a positive or negative score on every change you review. Use your best judgment. A note on Swift Core Maintainers -================================ +-------------------------------- Swift Core maintainers may provide positive reviews scores that *look* different from your reviews - a "+2" instead of a "+1". diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst new file mode 100644 index 0000000000..592cf90c85 --- /dev/null +++ b/doc/source/contributor/contributing.rst @@ -0,0 +1,79 @@ +.. include:: ../../../CONTRIBUTING.rst + +Community +========= + +Communication +------------- +IRC + People working on the Swift project may be found in the + ``#openstack-swift`` channel on Freenode during working hours + in their timezone. The channel is logged, so if you ask a question + when no one is around, you can check the log to see if it's been + answered: http://eavesdrop.openstack.org/irclogs/%23openstack-swift/ + +weekly meeting + This is a Swift team meeting. The discussion in this meeting is about + all things related to the Swift project: + +- time: http://eavesdrop.openstack.org/#Swift_Team_Meeting +- agenda: https://wiki.openstack.org/wiki/Meetings/Swift + +mailing list + We use the openstack-discuss@lists.openstack.org mailing list for + asynchronous discussions or to communicate with other OpenStack teams. + Use the prefix ``[swift]`` in your subject line (it's a high-volume + list, so most people use email filters). + + More information about the mailing list, including how to subscribe + and read the archives, can be found at: + http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-discuss + +Contacting the Core Team +------------------------ + +The swift-core team is an active group of contributors who are responsible +for directing and maintaining the Swift project. As a new contributor, your +interaction with this group will be mostly through code reviews, because +only members of swift-core can approve a code change to be merged into the +code repository. But the swift-core team also spend time on IRC so feel +free to drop in to ask questions or just to meet us. + +.. note:: + Although your contribution will require reviews by members of + swift-core, these aren't the only people whose reviews matter. + Anyone with a gerrit account can post reviews, so you can ask + other developers you know to review your code ... and you can + review theirs. (A good way to learn your way around the codebase + is to review other people's patches.) + + If you're thinking, "I'm new at this, how can I possibly provide + a helpful review?", take a look at `How to Review Changes the + OpenStack Way + `_. + + Or for more specifically in a Swift context read :doc:`review_guidelines` + +You can learn more about the role of core reviewers in the OpenStack +governance documentation: +https://docs.openstack.org/contributors/common/governance.html#core-reviewer + +The membership list of swift-core is maintained in gerrit: +https://review.opendev.org/#/admin/groups/24,members + +You can also find the members of the swift-core team at the Swift weekly +meetings. + +Getting Your Patch Merged +------------------------- +Understanding how reviewers review and what they look for will help getting +your code merged. See `Swift Review Guidelines `_ +for how we review code. + +Keep in mind that reviewers are also human; if something feels stalled, then +come and poke us on IRC or add it to our meeting agenda. + +Project Team Lead Duties +------------------------ +All common PTL duties are enumerated in the `PTL guide +`_. diff --git a/doc/source/contributor/review_guidelines.rst b/doc/source/contributor/review_guidelines.rst new file mode 100644 index 0000000000..314e764f49 --- /dev/null +++ b/doc/source/contributor/review_guidelines.rst @@ -0,0 +1 @@ +.. include:: ../../../REVIEW_GUIDELINES.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 9d3023aac8..7aeb82e70a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -66,6 +66,15 @@ Overview and Concepts ring_partpower associated_projects +Contributor Documentation +========================= + +.. toctree:: + :maxdepth: 2 + + contributor/contributing + contributor/review_guidelines + Developer Documentation =======================