From 3b51e8707aa3787f2b105ec90b564c68dff6c8a9 Mon Sep 17 00:00:00 2001 From: Matthew Treinish Date: Tue, 17 Mar 2020 16:13:47 -0400 Subject: [PATCH] Add missing pieces for Qiskit project standards This commit adds the missing pieces from the repository to bring it more inline with the rest of the projects under Qiskit. Mainly this means adding templates for bugs, enhancements, and pull requests in addition to adding a code of conduct and contributing guide. It also converts the README file to be markdown instead of rst to be consistent with the rest of Qiskit. --- .github/ISSUE_TEMPLATE/BUG_REPORT.md | 25 ++++ .github/ISSUE_TEMPLATE/ENHANCEMENT_REQUEST.md | 12 ++ .github/PULL_REQUEST_TEMPLATE.md | 9 ++ CODE_OF_CONDUCT.md | 83 +++++++++++++ CONTRIBUTING.md | 33 +++++ Cargo.toml | 2 +- README.md | 114 ++++++++++++++++++ README.rst | 102 ---------------- docs/source/README.rst | 2 +- docs/source/conf.py | 3 +- setup.py | 3 +- 11 files changed, 282 insertions(+), 106 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/BUG_REPORT.md create mode 100644 .github/ISSUE_TEMPLATE/ENHANCEMENT_REQUEST.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 README.md delete mode 100644 README.rst mode change 120000 => 100644 docs/source/README.rst diff --git a/.github/ISSUE_TEMPLATE/BUG_REPORT.md b/.github/ISSUE_TEMPLATE/BUG_REPORT.md new file mode 100644 index 0000000000..e8de61ff20 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/BUG_REPORT.md @@ -0,0 +1,25 @@ +--- +name: Bug report +about: Create a bug report +labels: bug +--- + + + + +### Information + +- **retworkx version**: +- **Python version**: +- **Rust version**: +- **Operating system**: + +### What is the current behavior? + + +### What is the expected behavior? + + +### Steps to reproduce the problem + + diff --git a/.github/ISSUE_TEMPLATE/ENHANCEMENT_REQUEST.md b/.github/ISSUE_TEMPLATE/ENHANCEMENT_REQUEST.md new file mode 100644 index 0000000000..570329719b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/ENHANCEMENT_REQUEST.md @@ -0,0 +1,12 @@ +--- +name: Enhancement request +about: Suggest an improvement for this project +labels: 'type: enhancement' +--- + + + + +### What is the expected enhancement? + + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000000..f4ab7aa975 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,9 @@ + diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000000..c79daed184 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,83 @@ +--- +title: Contributor Covenant Code of Conduct +--- + +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. + +Our Standards +============= + +Examples of behavior that contributes to creating a positive environment +include: + +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members + +Examples of unacceptable behavior by participants include: + +- The use of sexualized language or imagery and unwelcome sexual + attention or advances +- Trolling, insulting/derogatory comments, and personal or political + attacks +- Public or private harassment +- 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 +==================== + +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 +===== + +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 +=========== + +Instances of abusive, harassing, or otherwise unacceptable behavior may +be reported by contacting the project team at . 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 +=========== + +This Code of Conduct is adapted from the Contributor +[Covenant](http://contributor-covenant.org), +[version](http://contributor-covenant.org/version/1/4/) 1.4. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000000..7980da2d3a --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,33 @@ +# Contributing + +First read the overall project contributing guidelines. These are all +included in the qiskit documentation: + +https://qiskit.org/documentation/contributing_to_qiskit.html + +## Contributing to retworkx + +In addition to the general guidelines there are specific details for +contributing to retworkx, these are documented below. + +### Tests + +Once you've made a code change, it is important to verify that your change +does not break any existing tests and that any new tests that you've added +also run successfully. Before you open a new pull request for your change, +you'll want to run the test suite locally. + +Right now tests can only be run manually by invoking python's unittest (or +a compatible runner) directly from a python environment with retworkx compiled +and installed. To do this you run: + +```bash +python -m unittest discover . +``` + +from `./tests` in the repo (adjust `.` accordingly if you are running it from +another directoy). Note that you can **not** run the tests from the root of the +repo, this is because retworkx packaging shim will conflict with imports from +retworkx the installed version of retworkx (which contains the compiled +extension). + diff --git a/Cargo.toml b/Cargo.toml index 16d228f2b2..14fc8fb1f4 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4,7 +4,7 @@ description = "A python graph library implemented in Rust" version = "0.3.2" authors = ["Matthew Treinish "] license = "Apache-2.0" -readme = "README.rst" +readme = "README.md" repository = "https://github.com/Qiskit/retworkx" keywords = ["python", "graph"] diff --git a/README.md b/README.md new file mode 100644 index 0000000000..91859aa362 --- /dev/null +++ b/README.md @@ -0,0 +1,114 @@ +# retworkx + +[![License](https://img.shields.io/github/license/Qiskit/retworkx.svg?style=popout-square)](https://opensource.org/licenses/Apache-2.0)[![Build Status](https://img.shields.io/travis/com/Qiskit/retworkx/master.svg?style=popout-square)](https://travis-ci.com/Qiskit/retworkx)[![](https://img.shields.io/github/release/Qiskit/retworkx.svg?style=popout-square)](https://github.com/Qiskit/retworkx/releases)[![](https://img.shields.io/pypi/dm/retworkx.svg?style=popout-square)](https://pypi.org/project/retworkx/) + + - You can see the full rendered docs at: + + +retworkx is a rust graph library interface to python3. For right now +it's scope is as a replacement for +[qiskit-terra](https://github.com/Qiskit/qiskit-terra)'s previous (and +current) networkx usage (hence the name). The scope might grow or change +over time, but to start it's just about building a DAG and operating on +it with the performance and safety that Rust provides. + +## Installing retworkx + +retworkx is published on pypi so on x86\_64, i686, ppc64le, and aarch64 +Linux systems, x86\_64 on Mac OSX, and 32 and 64 bit Windows installing +is as simple as running: + +```bash +pip install retworkx +``` + +This will install a precompiled version of retworkx into your python +environment. + +However, if there are no precompiled binaries published for your system +you'll have to compile the code. The source package is also published on +pypi so you can also run the above command to install it. However, there +are 2 preconditions for this to work, first you need to have cargo/rustc +**nightly** in your PATH. You can use [rustup](https://rustup.rs/) to +make this step simpler. Secondly, you need to have `setuptools-rust` +installed in your python environment. This can can be done by simply +running: + +```bash +pip install setuptools-rust +``` + +prior to running: + +```bash +pip install retworkx +``` + +If you have rust nightly properly installed pip will compile retworkx +for your local system and it should run just as the prebuilt binaries +would. + +## Building from source + +The first step for building retworkx from source is to clone it locally +with: + +```bash +git clone https://github.com/Qiskit/retworkx.git +``` + +retworkx uses [PyO3](https://github.com/pyo3/pyo3) and +[setuptools-rust](https://github.com/PyO3/setuptools-rust) to build the +python interface. Unfortunately, this means you need to use nightly rust +because PyO3 only works with nightly at this point. You can use +[rustup](https://rustup.rs/) to install rust nightly. + +Once you have nightly rust and cargo installed you can easily install +retworkx into your python environment using pip. Once you have a local +clone of the repo, change your current working directory to the root of +the repo. To set the compiler for `retworkx` to nightly rust using +`rustup`, run the following from this directory: + +```bash +rustup override set nightly +``` + +then, you can install retworkx into your python env with: +```bash +pip install . +``` + +Assuming your current working directory is still the root of the repo. +Otherwise you can run: +```bash +pip install $PATH_TO_REPO_ROOT +``` + +which will install it the same way. Then retworkx is installed inyour +local python environment. There are 2 things to note when doing this +though, first if you try to run python from the repo root using this +method it will not work as you expect. There is a name conflict in the +repo root because of the local python package shim used in building the +package. Simply run your python scripts or programs using retworkx +outside of the repo root. The second issue is that any local changes you +make to the rust code will not be reflected live in the python you'll +need to recompile the source by rerunning pip install to have any +changes reflected in your python environment. + +## Using retworkx + +Once you have retworkx installed you can use it by importing retworkx. +All the functions and the PyDAG class are off the root of the package. +For example, building a DAG and adding 2 nodes with an edge between them +would be: + +```python +import retworkx + +my_dag = retworkx.PyDAG() +# add_node(), add_child(), and add_parent() return the node index +# The sole argument here can be any python object +root_node = my_dag.add_node("MyRoot") +# The second and third arguments can be any python object +my_dag.add_child(root_node, "AChild", ["EdgeData"]) +``` diff --git a/README.rst b/README.rst deleted file mode 100644 index dafaab02e0..0000000000 --- a/README.rst +++ /dev/null @@ -1,102 +0,0 @@ -retworkx -======== - -* You can see the full rendered docs at: https://retworkx.readthedocs.io/en/latest/index.html - - -retworkx is a rust graph library interface to python3. For right now it's scope -is as a replacement for `qiskit-terra`_'s previous (and current) networkx usage -(hence the name). The scope might grow or change over time, but to start it's -just about building a DAG and operating on it with the performance and safety -that Rust provides. - -.. _qiskit-terra: https://github.com/Qiskit/qiskit-terra - -Installing retworkx -------------------- - -retworkx is published on pypi so on x86_64, i686, ppc64le, and aarch64 Linux -systems, x86_64 on Mac OSX, and 32 and 64 bit Windows installing is as simple -as running:: - - pip install retworkx - -This will install a precompiled version of retworkx into your python -environment. - -However, if there are no precompiled binaries published for your system you'll -have to compile the code. The source package is also published on pypi so you -can also run the above command to install it. However, there are 2 -preconditions for this to work, first you need to have cargo/rustc **nightly** -in your PATH. You can use `rustup`_ to make this step simpler. Secondly, you -need to have ``setuptools-rust`` installed in your python environment. This can -can be done by simply running:: - - pip install setuptools-rust - -prior to running:: - - pip install retworkx - -If you have rust nightly properly installed pip will compile retworkx for your -local system and it should run just as the prebuilt binaries would. - -.. _rustup: https://rustup.rs/ - -Building from source --------------------- - -The first step for building retworkx from source is to clone it locally with:: - - git clone https://github.com/Qiskit/retworkx.git - -retworkx uses `PyO3`_ and `setuptools-rust`_ to build the python interface. -Unfortunately, this means you need to use nightly rust because PyO3 only works -with nightly at this point. You can use `rustup`_ to install rust nightly. - -.. _PyO3: https://github.com/pyo3/pyo3 -.. _setuptools-rust: https://github.com/PyO3/setuptools-rust -.. _rustup: https://rustup.rs/ - -Once you have nightly rust and cargo installed you can easily install retworkx -into your python environment using pip. Once you have a local clone of the repo, -change your current working directory to the root of the repo. To set the compiler -for ``retworkx`` to nightly rust using ``rustup``, run the following from this -directory:: - - rustup override set nightly - -then, you can install retworkx into your python env with:: - - pip install . - -Assuming your current working directory is still the root of the repo. Otherwise -you can run:: - - pip install $PATH_TO_REPO_ROOT - -which will install it the same way. Then retworkx is installed inyour local -python environment. There are 2 things to note when doing this though, first if -you try to run python from the repo root using this method it will not work as -you expect. There is a name conflict in the repo root because of the local python -package shim used in building the package. Simply run your python scripts or -programs using retworkx outside of the repo root. The second issue is that any -local changes you make to the rust code will not be reflected live in the -python you'll need to recompile the source by rerunning pip install to have any -changes reflected in your python environment. - -Using retworkx --------------- - -Once you have retworkx installed you can use it by importing retworkx. All -the functions and the PyDAG class are off the root of the package. For example, -building a DAG and adding 2 nodes with an edge between them would be:: - - import retworkx - - my_dag = retworkx.PyDAG() - # add_node(), add_child(), and add_parent() return the node index - # The sole argument here can be any python object - root_node = my_dag.add_node("MyRoot") - # The second and third arguments can be any python object - my_dag.add_child(root_node, "AChild", ["EdgeData"]) diff --git a/docs/source/README.rst b/docs/source/README.rst deleted file mode 120000 index c768ff7d97..0000000000 --- a/docs/source/README.rst +++ /dev/null @@ -1 +0,0 @@ -../../README.rst \ No newline at end of file diff --git a/docs/source/README.rst b/docs/source/README.rst new file mode 100644 index 0000000000..3bd447c431 --- /dev/null +++ b/docs/source/README.rst @@ -0,0 +1 @@ +.. mdinclude:: ../../README.md diff --git a/docs/source/conf.py b/docs/source/conf.py index 3f18a755c1..70a165fae1 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -27,6 +27,7 @@ extensions = ['sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.viewcode', + 'm2r', ] # Enable todos in the output @@ -36,7 +37,7 @@ templates_path = ['_templates'] # The suffix of source filenames. -source_suffix = '.rst' +source_suffix = ['.rst', '.md'] # The encoding of source files. #source_encoding = 'utf-8-sig' diff --git a/setup.py b/setup.py index f8f48f4def..f5cf1ae258 100644 --- a/setup.py +++ b/setup.py @@ -3,7 +3,7 @@ def readme(): - with open('README.rst') as f: + with open('README.md') as f: return f.read() setup( @@ -11,6 +11,7 @@ def readme(): version="0.3.2", description="A python graph library implemented in Rust", long_description=readme(), + long_description_content_type='text/markdown', author = "Matthew Treinish", author_email = "mtreinish@kortar.org", classifiers=[