diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..59b35f5 --- /dev/null +++ b/.gitignore @@ -0,0 +1,59 @@ +*.py[cod] + +# C extensions +*.so + +# Packages +*.egg* +*.egg-info +dist +build +eggs +parts +bin +var +sdist +develop-eggs +.installed.cfg +lib +lib64 + +# Installer logs +pip-log.txt + +# Unit test / coverage reports +cover/ +.coverage* +!.coveragerc +.tox +nosetests.xml +.testrepository +.stestr +.venv + +# Translations +*.mo + +# Mr Developer +.mr.developer.cfg +.project +.pydevproject + +# Complexity +output/*.html +output/*/index.html + +# Sphinx +doc/build + +# pbr generates these +AUTHORS +ChangeLog + +# Editors +*~ +.*.swp +.*sw? + +# Files created by releasenotes build +releasenotes/build diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..68c771a --- /dev/null +++ b/LICENSE @@ -0,0 +1,176 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..bda39e4 --- /dev/null +++ b/README.rst @@ -0,0 +1,18 @@ +=============================== +The OpenStack Contributor Guide +=============================== + +The Contributor Guide for the OpenStack project. + +To build the manual, execute the following command:: + + $ tox + +After running ``tox``, the documentation will be available for viewing +in HTML format in the ``doc/build/`` directory. + + +* Free software: Apache license +* Documentation: http://docs.openstack.org/developer/contributor-guide +* Source: http://git.openstack.org/cgit/openstack/contributor-guide +* Bugs: TODO diff --git a/doc/source/_assets/account-setup/1.png b/doc/source/_assets/account-setup/1.png new file mode 100644 index 0000000..27f3c3b Binary files /dev/null and b/doc/source/_assets/account-setup/1.png differ diff --git a/doc/source/_assets/account-setup/2.png b/doc/source/_assets/account-setup/2.png new file mode 100644 index 0000000..14aff96 Binary files /dev/null and b/doc/source/_assets/account-setup/2.png differ diff --git a/doc/source/_assets/account-setup/3.png b/doc/source/_assets/account-setup/3.png new file mode 100644 index 0000000..9e33196 Binary files /dev/null and b/doc/source/_assets/account-setup/3.png differ diff --git a/doc/source/_assets/account-setup/4.png b/doc/source/_assets/account-setup/4.png new file mode 100644 index 0000000..08a5a1b Binary files /dev/null and b/doc/source/_assets/account-setup/4.png differ diff --git a/doc/source/_assets/irc/linux/1.png b/doc/source/_assets/irc/linux/1.png new file mode 100644 index 0000000..88161ff Binary files /dev/null and b/doc/source/_assets/irc/linux/1.png differ diff --git a/doc/source/_assets/irc/linux/2.png b/doc/source/_assets/irc/linux/2.png new file mode 100644 index 0000000..62b0ff8 Binary files /dev/null and b/doc/source/_assets/irc/linux/2.png differ diff --git a/doc/source/_assets/irc/linux/3.png b/doc/source/_assets/irc/linux/3.png new file mode 100644 index 0000000..99af322 Binary files /dev/null and b/doc/source/_assets/irc/linux/3.png differ diff --git a/doc/source/_assets/irc/linux/4.png b/doc/source/_assets/irc/linux/4.png new file mode 100644 index 0000000..6c1bbbb Binary files /dev/null and b/doc/source/_assets/irc/linux/4.png differ diff --git a/doc/source/_assets/irc/linux/5.png b/doc/source/_assets/irc/linux/5.png new file mode 100644 index 0000000..b7c93eb Binary files /dev/null and b/doc/source/_assets/irc/linux/5.png differ diff --git a/doc/source/_assets/irc/macos/1.png b/doc/source/_assets/irc/macos/1.png new file mode 100644 index 0000000..1cbd52a Binary files /dev/null and b/doc/source/_assets/irc/macos/1.png differ diff --git a/doc/source/_assets/irc/macos/2.png b/doc/source/_assets/irc/macos/2.png new file mode 100644 index 0000000..f6a59f9 Binary files /dev/null and b/doc/source/_assets/irc/macos/2.png differ diff --git a/doc/source/_assets/irc/macos/3.png b/doc/source/_assets/irc/macos/3.png new file mode 100644 index 0000000..3858167 Binary files /dev/null and b/doc/source/_assets/irc/macos/3.png differ diff --git a/doc/source/_assets/irc/macos/4.png b/doc/source/_assets/irc/macos/4.png new file mode 100644 index 0000000..ef89cba Binary files /dev/null and b/doc/source/_assets/irc/macos/4.png differ diff --git a/doc/source/_assets/irc/macos/5.png b/doc/source/_assets/irc/macos/5.png new file mode 100644 index 0000000..f273a84 Binary files /dev/null and b/doc/source/_assets/irc/macos/5.png differ diff --git a/doc/source/accounts.rst b/doc/source/accounts.rst new file mode 100644 index 0000000..d6f897f --- /dev/null +++ b/doc/source/accounts.rst @@ -0,0 +1,205 @@ +############# +Account Setup +############# + +Setup Your OpenStack Foundation Account +======================================= + +What is the OpenStack Foundation Account? +----------------------------------------- +Allows you to: + +* Make code contributions. +* Vote in elections. +* Run for elected positions in the OpenStack project. +* Submit presentations to OpenStack conferences. + +Sign Up +------- +.. note:: + + Make sure to use the same email address you'll want to use for code + contributions since it's important later that these match up. + +#. Go to the `OpenStack Foundation sign up page + `_. +#. Under individual members, click the **Foundation Member** button. +#. Read through the presented individual member terms of service and our + `Community Code of Conduct + `_. +#. Complete the application. + +.. image:: _assets/account-setup/2.png + + +Setup Your Bug Tracker Account +============================== + +.. note:: + The OpenStack community is currently in the process of moving from the bug + tracking software Launchpad to StoryBoard. Further in the project specific + on-boarding documentation, give special attention if the project is using + Launchpad or StoryBoard. + +StoryBoard +---------- + +What is StoryBoard? +^^^^^^^^^^^^^^^^^^^ +`StoryBoard `_ is bug tracking software the +OpenStack community is `developing +`_, and in the progress of +`migrating towards +`_. +Some `projects are already using it +`_. + +Sign Up +^^^^^^^ +#. Go to the `storyboard.openstack.org `_. +#. On the top right corner, click the **login** button. +#. If you already have an Ubuntu One Account, you can just login. +#. If you don't have a Ubuntu One Account, click the **I am a new Ubuntu One + user**. +#. Fill in your email address, name, password, and accepting the terms of + services. + +.. image:: _assets/account-setup/1.png + + +Launchpad +--------- + +What is Launchpad? +^^^^^^^^^^^^^^^^^^ +`Launchpad `_ is the legacy way the OpenStack +community does bug tracking since we started `moving towards StoryBoard +`_. + +Sign Up +^^^^^^^ +You're already signed up. Launchpad uses your Ubuntu One account for +authentication like StoryBoard. + + +Setup Your Gerrit Account +========================= + +What is Gerrit? +--------------- +This is the review system the OpenStack community uses. Here are just some of +the things we use Gerrit for reviewing: + +* `Code `_ +* `Specifications `_ +* `Translations `_ +* `Use cases for features + `_ + +Sign Up +------- +#. Visit `OpenStack's Gerrit page `_ and click + the **sign in** link. +#. You will be prompted to select a username. You can enter the same one you + did for launchpad, or something else. + +.. note:: + + Choose and type your username carefully. + Once it is set, you cannot change the username. + +.. note:: + + From here on out when you sign into Gerrit, you'll be prompted to enter your + your Launchpad login info. This is because Gerrit uses it as an OpenID single + sign on. + + +Individual Contributor License Agreement +======================================== + +What is it? +----------- +An agreement to clarify intellectual property license granted with +contributions from a person or entity. `Preview the full agreement +`_. + +Signing it +---------- + +Individual Contributors +^^^^^^^^^^^^^^^^^^^^^^^ + +#. In Gerrit's `settings `_ + click the **New Contributor Agreement** link and sign the agreement. + +.. image:: _assets/account-setup/3.png + +Contributors From a Company or Organization +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +If you are contributing on behalf of a company or organization. + +#. In Gerrit's `settings `_ + click the **New Contributor Agreement** link and sign the agreement. + + .. image:: _assets/account-setup/3.png + +#. An employer with the appropriate signing rights of the company or + organization needs to sign the `Corporate Contributor License Agreement + `_. +#. If the CCLA only needs to be extended follow `this + `_ procedure. + +.. note:: + + Employers can update the list of authorized employees by filling out and + signing an `Updated Schedule + A Form + `_. + +Contributors From the U.S. Government +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +#. Someone of authority needs to sign the `U.S. Government Contributor License + Agreement `_. Contact the + `OpenStack Foundation `_ to initiate + this process. + +Contact Information +=================== + +What is it? +----------- + +You need to register your contact information including your full name, email +address and offline contact information. + +Your full name and email address will be public and the email address needs to +match the email address which you plan to use in your commits. + +The other contact information including postal address and phone numbers will +be kept confidential and is only used as a fallback record in the unlikely +event the OpenStack Foundation needs to reach you directly over code +contribution related matters. + +This contact information can be easily updated later if desired, but make sure +the primary email address always matches the one you set for your OpenStack +Foundation Membership. Otherwise, Gerrit will give you an error message and +refuse to accept your contact information. + +Register Contact Information +---------------------------- + +#. Visit `Contact Information + `__ + in Gerrit's settings. +#. Fill your contact information and click 'Save Changes'. +#. Once your contact information is saved successfully, + you will see the line **"Contact information last updated ...."** + just above the forms of mailing address. + +.. image:: _assets/account-setup/4.png + +.. important:: + + If you do not register your contact information, + you cannot upload any changes to Gerrit. diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100755 index 0000000..403340c --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,84 @@ +# -*- coding: utf-8 -*- +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +import os +import sys + +sys.path.insert(0, os.path.abspath('../..')) +# -- General configuration ---------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = [ + 'sphinx.ext.autodoc', + 'openstackdocstheme', + #'sphinx.ext.intersphinx', +] + +# autodoc generation is a bit aggressive and a nuisance when doing heavy +# text edit cycles. +# execute "export SPHINX_DEBUG=1" in your terminal to disable + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'contributor-guide' +copyright = u'2017, OpenStack Developers' + +# openstackdocstheme options +repository_name = 'openstack/contributor-guide' +bug_project = 'openstack-contributor-guide' +bug_tag = '' + +# If true, '()' will be appended to :func: etc. cross-reference text. +add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +add_module_names = True + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# -- Options for HTML output -------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +# html_theme_path = ["."] +# html_theme = '_theme' +# html_static_path = ['static'] +html_theme = 'openstackdocs' + +# Must set this variable to include year, month, day, hours, and minutes. +html_last_updated_fmt = '%Y-%m-%d %H:%M' + +# Output file base name for HTML help builder. +htmlhelp_basename = '%sdoc' % project + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass +# [howto/manual]). +latex_documents = [ + ('index', + '%s.tex' % project, + u'%s Documentation' % project, + u'OpenStack Developers', 'manual'), +] + +# Example configuration for intersphinx: refer to the Python standard library. +#intersphinx_mapping = {'http://docs.python.org/': None} diff --git a/doc/source/git.rst b/doc/source/git.rst new file mode 100644 index 0000000..f6fe00b --- /dev/null +++ b/doc/source/git.rst @@ -0,0 +1,226 @@ +################### +Setup and Learn GIT +################### + +.. note:: + + This section assumes you have completed :doc:`accounts` guide. + +Git +=== + +What is it? +----------- + +Git is a free and open source distributed version control system that the +OpenStack community uses to manage changes to source code. + +Installation +------------ + +Mac OS +^^^^^^ + +#. Go to the Git `download page `_ and click + **Mac OS X**. + +#. The downloaded file should be a dmg in your downloads folder. Open that dmg + file and follow the instructions on screen. + +If you use the package manager `Homebrew `_, open a terminal +and type:: + + brew install git + +Linux +^^^^^ + +For distributions like Debian, Ubuntu, or Mint open a terminal and type:: + + sudo apt install git + +For distributions like RedHat, Fedora 21 or earlier, or CentOS open a terminal +and type:: + + sudo yum install git + +For Fedora 22 or later open a terminal and type:: + + sudo dnf install git + +For SUSE distributions open a terminal and type:: + + sudo zypper in git + +Configure Git +------------- + +Once you have Git installed you need to configure it. Open your terminal +application and issue the following commands putting in your first/last name +and email address. This is how your contributions will be identified:: + + git config --global user.name "Firstname Lastname" + git config --global user.email "your_email@youremail.com" + +Git Review +========== + +What is it? +----------- + +Git review is tool maintained by the OpenStack community. It adds an additional +sub-command to git like so:: + + git review + +When you have changes in an OpenStack project repository, you can use this +sub-command to have the changes posted to +`Gerrit `__ so that they can be reviewed. + +Installation +------------ + +Mac OS +^^^^^^ + +In a terminal type:: + + pip install git-review + +If you don't have pip installed already, follow the `installation documentation +`_ for +pip. + +.. note:: + + Mac OS X El Capitan and macOS Sierra users might see an error + message like "Operation not permitted" when installing with the command. + In this case, there are two options to successfully install git-review. + + Option 1: install using pip with more options:: + + pip install --install-option '--install-data=/usr/local' git-review + + Option 2: Use the package manager `Homebrew `_, + and type in a terminal:: + + brew install git-review + +Linux +^^^^^^ + +For distributions like Debian, Ubuntu, or Mint open a terminal and type:: + + sudo apt install git-review + +For distributions like RedHat, Fedora 21 or earlier, or CentOS open a terminal +and type:: + + sudo yum install git-review + +For Fedora 22 or later open a terminal and type:: + + sudo dnf install git-review + +For SUSE distributions open a terminal and type:: + + sudo zypper in python-git-review + +Configuration +------------- + +Git review assumes the user you're running it as is the same as your Gerrit +username. If it's not, you can tell it by setting this git config setting:: + + git config --global gitreview.username + +If you don't know what your Gerrit username is, you can check the `Gerrit +settings `_. + +Setup SSH Keys +============== + +What are they? +-------------- + +In order to push things to `Gerrit `_ we need to +have a way to identify ourselves. We will do this using ssh keys which allows +us to have our machine we're pushing a change from to perform +a `challenge-response authentication +`_ with the +Gerrit server. + +SSH keys are always generated in pairs: + +* **Private key** - Only known to you and it should be safely guarded. +* **Public key** - Can be shared freely with any SSH server you wish to connect + to. + +In summary, we will be generating these keys, and providing the Gerrit server +with your public key. With your system holding the private key, it will have no +problem replying to Gerrit during the challenge-response authentication. + + +Check For Existing Keys +----------------------- + +Open your terminal program and type:: + + ls -la ~/.ssh + +Typically public key filenames will look like: + +* id_dsa.pub +* id_ecdsa.pub +* id_ed25519.pub +* id_rsa.pub + +If you don't see .pub extension file, you need to generate keys. + + +Generate SSH Keys +----------------- + +Assuming you weren't able to find keys in your ~/.ssh directory, you can +generate a new ssh key using the provided email as a label by going into +your terminal program and typing:: + + ssh-keygen -t rsa -b 4096 -C "your_email@example.com" + +When you're prompted to "Enter a file in which to save the key" press Enter. +This accepts the default location:: + + Enter a file in which to save the key (/Users/you/.ssh/id_rsa): [Press enter] + +At the prompt, type a secure a passphrase, you may enter one or press Enter to +have no passphrase:: + + Enter passphrase (empty for no passphrase): [Type a passphrase] + Enter same passphrase again: [Type passphrase again] + + +Copy Public Key +--------------- + +Mac OS & Linux +^^^^^^^^^^^^^^ + +From your terminal type:: + + cat ~/.ssh/id_rsa.pub + +Highlight and copy the output. + +Import Public Key Into Gerrit +----------------------------- + +#. Go to `Gerrit's SSH Public Keys settings + `_. +#. Click the 'Add Key' button. +#. Paste the public key into the **Add SSH Public Key** text box and click Add. + +Learning Git +============ + +You can use `Git Immersion `_ to work +through tutorials for learning git. diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..e4d4560 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,25 @@ +.. contributor-guide documentation master file, created by + sphinx-quickstart on Tue Jul 9 22:26:36 2013. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +=============================== +The OpenStack Contributor Guide +=============================== + +Contents: + +.. toctree:: + :maxdepth: 2 + + readme + irc + accounts + git + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/doc/source/irc.rst b/doc/source/irc.rst new file mode 100644 index 0000000..612c095 --- /dev/null +++ b/doc/source/irc.rst @@ -0,0 +1,197 @@ +######### +Setup IRC +######### + +Linux & Windows +=============== + +Install an IRC Program +---------------------- +We will install an IRC program called Hexchat. + +For a Linux distributions like Debian, Ubuntu, or Mint open a terminal and +type:: + + sudo apt install hexchat + +For a Linux distributions like Redhat, Fedora 21 or earlier, or CentOS open +a terminal and type:: + + sudo yum install hexchat + +For Fedora 22 or later open a terminal and type:: + + sudo dnf install hexchat + +For Windows environment, download latest Hexchat installation binary from +`Hexchat download `__ and +install it. +You will probably also need extra components shown just under Hexchat. + +Now open the hexchat program just like you would for any Linux program. + + +Edit Nick Name Settings +----------------------- +#. Lets first fill out the **Nick name** and **User name** field with our + choice of a nickname: +#. From the list of **Networks** you should see Freenode. Select that and click + 'edit'. + +.. image:: _assets/irc/linux/1.png + + +Edit Server Settings +-------------------- +#. Click the **edit** button and +#. Make sure that **Use SSL for all the servers on this network** is + checked. + +.. image:: _assets/irc/linux/2.png + +Troubleshooting +^^^^^^^^^^^^^^^ +* If you get a notice that the nick name is already taken, quit and go back to + the first set of steps to pick a different nickname. + + +Register Your Nick Name +----------------------- +If all goes well we should get a dialog window indicating the connection to +freenode has completed, and what to do next.. For now we'll select "Nothing, +I'll join a channel later." + +.. image:: _assets/irc/linux/3.png + +When you login to the server for the first time with your nickname, its being +used by you, but it's still not registered yet. + +In order to register we need to send a message to nickserv on freenode, which +is a bot that allows us to register and identify ourselves as the owner of +a nick name. + +Type the following to register your nick name with nickserv replacing +**mysecretpassword** and **test@domain.com** with your own password and email +address:: + + /msg nickserv register mysecretpassword test@domain.com + +.. image:: _assets/irc/linux/4.png + +If all goes well you should receive a message back instantly that the nick name +is registered by you and an activation email will be sent to the email address +you provided. + + + +Auto-Login On Connecting To Freenode +------------------------------------ +In order to identify ourselves that we own the nick name upon logging in, we +need to tell Hexchat to communicate our password over upon connecting. + +#. Click **Hexchat** from the menu and then click **Network List**. We will see + a familiar first screen of servers listed. Make sure freenode is highlighted + and click **edit**. +#. In the **Password** put in the password we picked in the previous + step and click close. + +.. image:: _assets/irc/linux/5.png + + +Done +---- +Congratulations you're now ready to communicate with the OpenStack community +and have a registered nick name on Freenode! From here on out when you connect +to Freenode with Hexchat you will be identified with your nickname. + + +Mac OS +====== + +Install an IRC Program +---------------------- +We'll install an IRC program called Colloquy. + +#. Go to http://colloquy.info and follow the download link. +#. From your downloads folder, drag the Colloquy application icon to your + applications folder to install. + + +Add A New Connection +-------------------- +#. Lets first fill out the **Nickname** and **User name** field with our + choice of a nickname: +#. For the **Chat server** type in **irc.freenode.net**. +#. For the **Chat Server Port** type in **6697** and check the **SSL + Connection** box. + +.. image:: _assets/irc/macos/1.png + :width: 50% + +If all goes well in the second window we should see our our new connection and +our client connected. + +.. image:: _assets/irc/macos/2.png + :width: 50% + +Troubleshooting +^^^^^^^^^^^^^^^ +* If you get a notice that the nick name is already taken + * Click **cancel**. + * Click the **info** icon. + * Type in a different user/nick name as shown in the previous step. + * Click **disconnect** and click **connect** to retry connecting with the + new nick name. + +.. image:: _assets/irc/macos/3.png + :width: 50% + + +Register Your Nick Name +----------------------- +If all goes well we should be connected and no pop ups as indicted in the +previous step's Troubleshooting section. + +When you login to the server for the first time with your nickname, its being +used by you, but it's still not registered yet. + +In order to register we need to send a message to nickserv on freenode, which +is a bot that allows us to register and identify ourselves as the owner of +a nick name. + +Click the **message user** icon and type:: + + nickserv + +A message dialog window will come up. Type the following to register your nick +name with nickserv replacing **mysecretpassword** and **test@domain.com** with +your own password and email address:: + + register mysecretpassword test@domain.com + +.. image:: _assets/irc/macos/4.png + :width: 90% + +If all goes well you should receive a message back instantly that the nick name +is registered by you and an activation email will be sent to the email address +you provided. + + +Auto-Login On Connecting To Freenode +------------------------------------ +In order to identify ourselves that we own the nick name upon logging in, we +need to tell Colloquy to communicate our password over upon connecting. + +#. Going back to your connection window, highlight your freenode connection and + click the **info** icon. +#. In the **Password** field type your password. + +.. image:: _assets/irc/macos/5.png + :width: 50% + + +Done +---- +Congratulations you're now ready to communicate with the OpenStack community +and have a registered nick name on Freenode! From here on out when you connect +to Freenode with Colloquy you will be identified with your nickname. diff --git a/doc/source/readme.rst b/doc/source/readme.rst new file mode 100644 index 0000000..a6210d3 --- /dev/null +++ b/doc/source/readme.rst @@ -0,0 +1 @@ +.. include:: ../../README.rst diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..3f81433 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,7 @@ +# The order of packages is significant, because pip processes them in the order +# of appearance. Changing the order has an impact on the overall integration +# process, which may cause wedges in the gate later. + +pbr>=2.0 # Apache-2.0 +sphinx>=1.6.2 # BSD +openstackdocstheme>=1.11.0 # Apache-2.0 diff --git a/setup.cfg b/setup.cfg new file mode 100644 index 0000000..f6f3189 --- /dev/null +++ b/setup.cfg @@ -0,0 +1,26 @@ +[metadata] +name = contributor-guide +summary = The Contributor Guide for the OpenStack project. +description-file = + README.rst +author = OpenStack +author-email = openstack-dev@lists.openstack.org +home-page = http://www.openstack.org/ +classifier = + Environment :: OpenStack + Intended Audience :: Information Technology + Intended Audience :: System Administrators + License :: OSI Approved :: Apache Software License + Operating System :: POSIX :: Linux + Programming Language :: Python + Programming Language :: Python :: 2 + Programming Language :: Python :: 2.7 + Programming Language :: Python :: 3 + Programming Language :: Python :: 3.3 + Programming Language :: Python :: 3.4 + +[build_sphinx] +all-files = 1 +warning-is-error = 1 +source-dir = doc/source +build-dir = doc/build diff --git a/setup.py b/setup.py new file mode 100644 index 0000000..056c16c --- /dev/null +++ b/setup.py @@ -0,0 +1,29 @@ +# Copyright (c) 2013 Hewlett-Packard Development Company, L.P. +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or +# implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# THIS FILE IS MANAGED BY THE GLOBAL REQUIREMENTS REPO - DO NOT EDIT +import setuptools + +# In python < 2.7.4, a lazy loading of package `pbr` will break +# setuptools if some other modules registered functions in `atexit`. +# solution from: http://bugs.python.org/issue15881#msg170215 +try: + import multiprocessing # noqa +except ImportError: + pass + +setuptools.setup( + setup_requires=['pbr'], + pbr=True) diff --git a/tox.ini b/tox.ini new file mode 100644 index 0000000..e3b8655 --- /dev/null +++ b/tox.ini @@ -0,0 +1,16 @@ +[tox] +minversion = 2.0 +envlist = checkbuild +skipsdist = True + +[testenv] +usedevelop = True +setenv = VIRTUAL_ENV={envdir} +install_command = pip install -U {opts} {packages} +deps = -r{toxinidir}/requirements.txt + +[testenv:venv] +commands = {posargs} + +[testenv:docs] +commands = python setup.py build_sphinx