Merge pull request #290 from manoelmarques/stable-0.4.1

New Release 0.4.1

Author: manoelmarques

.github/CODE_OF_CONDUCT.md renamed to .github/CODE_OF_CONDUCT.rst

@@ -1,10 +1,17 @@
-# Contributor Covenant Code of Conduct
+Contributor Covenant Code of Conduct
+====================================
 
-## Our Pledge
+Our Pledge
+----------
 
-In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers
+pledge to making participation in our project and our community a harassment-free
+experience for everyone, regardless of age, body size, disability, ethnicity, gender
+identity and expression, level of experience, nationality, personal appearance, race,
+religion, or sexual identity and orientation.
 
-## Our Standards
+Our Standards
+-------------
 
 Examples of behavior that contributes to creating a positive environment include:
 
@@ -22,25 +29,29 @@ Examples of unacceptable behavior by participants include:
 * Publishing others' private information, such as a physical or electronic address, without explicit permission
 * Other conduct which could reasonably be considered inappropriate in a professional setting
 
-## Our Responsibilities
+Our Responsibilities
+--------------------
 
 Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
 
 Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
 
-## Scope
+Scope
+-----
 
 This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
 
-## Enforcement
+Enforcement
+-----------
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at conduct@qiskit.org. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at qiskit@qiskit.org. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
 
 Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
 
-## Attribution
+Attribution
+-----------
 
-This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]
+This Code of Conduct is adapted from the Contributor `Covenant`_, `version`_ 1.4.
 
-[homepage]: http://contributor-covenant.org
-[version]: http://contributor-covenant.org/version/1/4/
+.. _Covenant: http://contributor-covenant.org
+.. _version: http://contributor-covenant.org/version/1/4/

.github/CONTRIBUTING.rst

@@ -3,103 +3,121 @@ Contributing
 
 **We appreciate all kinds of help, so thank you!**
 
-Contributing to the project
+
+Contributing to the Project
 ---------------------------
 
 You can contribute in many ways to this project.
 
-Issue reporting
+
+Issue Reporting
 ~~~~~~~~~~~~~~~
 
 This is a good point to start, when you find a problem please add
-it to the `issue tracker <https://github.com/Qiskit/aqua/issues>`_.
+it to the `issue tracker <https://github.com/Qiskit/qiskit-aqua/issues>`_.
 The ideal report should include the steps to reproduce it.
 
-Doubts solving
+
+Doubts Solving
 ~~~~~~~~~~~~~~
 
 To help less advanced users is another wonderful way to start. You can
-help us close some opened issues. This kind of tickets should be
+help us close some opened issues. A ticket of this kind should be
 labeled as ``question``.
 
-Improvement proposal
+
+Improvement Proposal
 ~~~~~~~~~~~~~~~~~~~~
 
-If you have an idea for a new feature please open a ticket labeled as
+If you have an idea for a new feature, please open a ticket labeled as
 ``enhancement``. If you could also add a piece of code with the idea
-or a partial implementation it would be awesome.
+or a partial implementation, that would be awesome.
+
 
 Contributor License Agreement
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 We'd love to accept your code! Before we can, we have to get a few legal
-requirements sorted out. By signing a contributor license agreement (CLA), we
+requirements sorted out. By signing a Contributor License Agreement (CLA), we
 ensure that the community is free to use your contributions.
 
-When you contribute to the Qiskit project with a new pull request, a bot will
+When you contribute to the Qiskit Aqua project with a new pull request, a bot will
 evaluate whether you have signed the CLA. If required, the bot will comment on
 the pull request,  including a link to accept the agreement. The
 `individual CLA <https://qiskit.org/license/qiskit-cla.pdf>`_ document is
 available for review as a PDF.
 
-NOTE: If you work for a company that wants to allow you to contribute your work,
-then you'll need to sign a `corporate CLA <https://qiskit.org/license/qiskit-corporate-cla.pdf>`_
-and email it to us at qiskit@us.ibm.com.
-
-Code
-----
-
-This section include some tips that will help you to push source code.
+.. note::
+    If you work for a company that wants to allow you to contribute your work,
+    then you'll need to sign a `corporate CLA <https://qiskit.org/license/qiskit-corporate-cla.pdf>`_
+    and email it to us at qiskit@us.ibm.com.
 
 
-Style guide
-~~~~~~~~~~~
-
-Please submit clean code and please make effort to follow existing conventions
-in order to keep it as readable as possible. We use
-`Pylint <https://www.pylint.org>`_ and `PEP
-8 <https://www.python.org/dev/peps/pep-0008>`_ style guide.
-
-Good first contributions
+Good First Contributions
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
 You are welcome to contribute wherever in the code you want to, of course, but
-we recommend taking a look at the "Good first contribution" label into the
+we recommend taking a look at the "Good First Contribution" label into the
 issues and pick one. We would love to mentor you!
 
+
 Doc
 ~~~
 
 Review the parts of the documentation regarding the new changes and update it
 if it's needed.
 
-Pull requests
+
+Pull Requests
 ~~~~~~~~~~~~~
 
 We use `GitHub pull requests <https://help.github.com/articles/about-pull-requests>`_
 to accept the contributions.
 
 A friendly reminder! We'd love to have a previous discussion about the best way to
 implement the feature/bug you are contributing with. This is a good way to
-improve code quality in our beloved SDK!, so remember to file a new Issue before
+improve code quality in our beloved Qiskit Aqua! So remember to file a new issue before
 starting to code for a solution.
 
-So after having discussed the best way to land your changes into the codebase,
-you are ready to start coding (yay!). We have two options here:
+After having discussed the best way to land your changes into the codebase,
+you are ready to start coding. We have two options here:
 
 1. You think your implementation doesn't introduce a lot of code, right?. Ok,
    no problem, you are all set to create the PR once you have finished coding.
    We are waiting for it!
 2. Your implementation does introduce many things in the codebase. That sounds
-   great! Thanks!. In this case you can start coding and create a PR with the
+   great! Thanks! In this case, you can start coding and create a PR with the
    word: **[WIP]** as a prefix of the description. This means "Work In
-   Progress", and allow reviewers to make micro reviews from time to time
-   without waiting to the big and final solution... otherwise, it would make
+   Progress", and allows reviewers to make micro reviews from time to time
+   without waiting for the big and final solution. Otherwise, it would make
    reviewing and coming changes pretty difficult to accomplish. The reviewer
    will remove the **[WIP]** prefix from the description once the PR is ready
    to merge.
 
-Please follow the next rules for the commit messages:
+
+Pull Request Checklist
+""""""""""""""""""""""
+
+When submitting a pull request and you feel it is ready for review, please
+double check that:
+
+* The code follows the code style of the project. For convenience, you can
+  execute ``make style`` and ``make lint`` locally, which will print potential
+  style warnings and fixes.
+* The documentation has been updated accordingly. In particular, if a function
+  or class has been modified during the PR, please update the docstring
+  accordingly.
+* Your contribution passes the existing tests, and if developing a new feature,
+  that you have added new tests that cover those changes.
+* You add a new line to the ``CHANGELOG.rst`` file, in the ``UNRELEASED``
+  section, with the title of your pull request and its identifier (for example,
+  "``Replace OldComponent with FluxCapacitor (#123)``".
+
+
+Commit Messages
+"""""""""""""""
+
+Please follow the next rules for any commit message:
 
 - It should include a reference to the issue ID in the first line of the commit,
   **and** a brief description of the issue, so everybody knows what this ID
@@ -111,17 +129,69 @@ Please follow the next rules for the commit messages:
 
 A good example:
 
-.. code::
+.. code-block:: text
 
     Issue #190: Short summary of the issue
     * One of the important changes
     * Another important change
 
-A (really) bad example:
 
-.. code::
+Code
+----
+
+This section include some tips that will help you to push source code.
+
+.. note::
+
+    We recommend using `Python virtual environments <https://docs.python.org/3/tutorial/venv.html>`__
+    to cleanly separate Qiskit from other applications and improve your experience.
+
+
+Setup with an Environment
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The simplest way to use environments is by using Anaconda
+
+.. code:: sh
 
-    Fixes #190
+    conda create -y -n QiskitDevenv python=3
+    source activate QiskitDevenv
+
+In order to execute the Aqua code, after cloning the Aqua GitHub repository on your machine,
+you need to have some libraries, which can be installed in this way:
+
+.. code:: sh
+
+    cd qiskit-aqua
+    pip install -r requirements.txt
+    pip install -r requirements-dev.txt
+
+To install Qiskit Aqua locally, execute the following command from the `qiskit-aqua` root
+directory on your machine:
+
+.. code:: sh
+
+    $ pip install -e .
+
+Installing Aqua will automatically install `Terra <https://github.com/Qiskit/qiskit-terra>`__
+as one of its dependencies.  We recommend that you also set up
+`Aer <https://github.com/Qiskit/qiskit-aer>`__ to get more advanced simulators.
+Refer to the installation instructions of both Terra and Aer for more details.
+
+Style guide
+~~~~~~~~~~~
+
+Please submit clean code and please make effort to follow existing conventions
+in order to keep it as readable as possible. We use the
+`Pylint <https://www.pylint.org>`_ and `PEP
+8 <https://www.python.org/dev/peps/pep-0008>`_ style guide. To ensure
+your changes respect the style guidelines, run the next commands (all platforms):
+
+.. code:: sh
+
+    $> cd out
+    out$> make lint
+    out$> make style
 
 
 Documentation
@@ -138,14 +208,70 @@ documentation <http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_go
 
 To generate the documentation, we need to invoke CMake first in order to generate
 all specific files for our current platform.
+See the `instructions <https://github.com/Qiskit/qiskit-terra/blob/master/.github/CONTRIBUTING.rst#dependencies>`__
+in the Terra repository for details on how to install and run CMake.
+The docunentation can then be built using the instructions available in the
+`docs folder's README file <../docs/README.md>`__.
 
-See the previous *Building* section for details on how to run CMake.
-Once CMake is invoked, all configuration files are in place, so we can build the
-documentation running this command:
 
-All platforms:
+Development Cycle
+-----------------
 
-.. code:: sh
+Our development cycle is straightforward. Use the **Projects** board in Github
+for project management and use **Milestones** in the **Issues** board for releases. The features
+that we want to include in these releases will be tagged and discussed
+in the project boards. Whenever a new release is close to be launched,
+we'll announce it and detail what has changed since the latest version in
+our Release Notes and Changelog. The channels we'll use to announce new
+releases are still being discussed, but for now, you can
+`follow us <https://twitter.com/qiskit>`_ on Twitter!
 
-    $> cd out
-    doc$> make doc
+
+Branch Model
+~~~~~~~~~~~~
+
+There are two main branches in the repository:
+
+- ``master``
+
+  - This is the development branch.
+  - Next release is going to be developed here. For example, if the current
+    latest release version is r1.0.3, the master branch version will point to
+    r1.1.0 (or r2.0.0).
+  - You should expect this branch to be updated very frequently.
+  - Even though we are always doing our best to not push code that breaks
+    things, is more likely to eventually push code that breaks something...
+    we will fix it ASAP, promise :).
+  - This should not be considered as a stable branch to use in production
+    environments.
+  - The API of Qiskit could change without prior notice.
+
+- ``stable``
+
+  - This is our stable release branch.
+  - It's always synchronized with the latest distributed package: as for now,
+    the package you can download from pip.
+  - The code in this branch is well tested and should be free of errors
+    (unfortunately sometimes it's not).
+  - This is a stable branch (as the name suggest), meaning that you can expect
+    stable software ready for production environments.
+  - All the tags from the release versions are created from this branch.
+
+
+Release Cycle
+~~~~~~~~~~~~~
+
+From time to time, we will release brand new versions of Qiskit Terra. These
+are well-tested versions of the software.
+
+When the time for a new release has come, we will:
+
+1. Merge the ``master`` branch with the ``stable`` branch.
+2. Create a new tag with the version number in the ``stable`` branch.
+3. Crate and distribute the pip package.
+4. Change the ``master`` version to the next release version.
+5. Announce the new version to the world!
+
+The ``stable`` branch should only receive changes in the form of bug fixes, so the
+third version number (the maintenance number: [major].[minor].[maintenance])
+will increase on every new change.