diff --git a/.github/CODE_OF_CONDUCT.md b/.github/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..c7672f8 --- /dev/null +++ b/.github/CODE_OF_CONDUCT.md @@ -0,0 +1,58 @@ +# Community Code of Conduct + +In the IOTA community, participants from all over the world come together to create. This is made possible by the support, hard work and enthusiasm of thousands of people, including those who create and use the IOTA technology. + +This document offers some guidance to ensure IOTA participants can cooperate effectively in a positive and inspiring atmosphere, and to explain how together we can strengthen and support each other. + +This Code of Conduct is shared by all contributors and users who engage with the IOTA Foundation team and its community services. + +## Overview + +This Code of Conduct presents a summary of the shared values and “common sense” thinking in our community. The basic social ingredients that hold our project together include: + +- Being considerate +- Being respectful +- Being collaborative +- Being pragmatic +- Supporting others in the community +- Getting support from others in the community + +This Code of Conduct reflects the agreed standards of behavior for members of the IOTA community, in any social media platform, forum, mailing list, wiki, web site, discord channel, public meeting or private correspondence within the context of the IOTA Foundation team and the IOTA Tangle technology. The community acts according to the standards written down in this Code of Conduct and will defend these standards for the benefit of the community. Leaders of any group, such as moderators of social media groups, mailing lists, discord channels, forums, etc., will exercise the right to suspend access to any person who persistently breaks our shared Code of Conduct. + +## Be considerate + +Your actions and work will affect and be used by other people and you, in turn, will depend on the work and actions of others. Any decision you take will affect other community members, and we expect you to take those consequences into account when making decisions. + +As a user, remember that community members work hard on their part of IOTA and take great pride in it. + +## Be respectful + +In order for the IOTA community to stay healthy, its members must feel comfortable and accepted. Treating one another with respect is absolutely necessary for this. In a disagreement, in the first instance, assume that people mean well. + +We do not tolerate personal attacks, racism, sexism or any other form of discrimination. Disagreement is inevitable, from time to time, but respect for the views of others will go a long way to winning respect for your own view. Respecting other people, their work, their contributions and assuming well-meaning motivation will make community members feel comfortable and safe and will result in motivation and productivity. + +We expect members of our community to be respectful when dealing with other contributors, users, and communities. Remember that IOTA is an international project and that you may be unaware of important aspects of other cultures. + +## Be collaborative + +Your feedback is important, as is its form. Poorly thought out comments can cause pain and the demotivation of other community members, but considerate discussion of problems can bring positive results. An encouraging word works wonders. + +## Be pragmatic + +The IOTA community is pragmatic and fair. We value tangible results over having the last word in a discussion. We defend our core values like freedom and respectful collaboration, but we don’t let arguments about minor issues get in the way of achieving more important results. We are open to suggestions and welcome solutions regardless of their origin. When in doubt support a solution which helps to get things done over one which has theoretical merits, but isn’t being worked on. Use the tools and methods which help to get the job done. Let decisions be taken by those who do the work. + +## Support others in the community + +The IOTA community is made strong by mutual respect, collaboration and pragmatic, responsible behavior. Sometimes there are situations where this has to be defended and other community members need help. + +If you witness others being attacked, think first about how you can offer them personal support. If you feel that the situation is beyond your ability to help individually, go privately to the victim and ask if some form of official intervention is needed. + +When problems do arise, consider respectfully reminding those involved of our shared Code of Conduct as a first action. Leaders are defined by their actions and can help set a good example by working to resolve issues in the spirit of this Code of Conduct before they escalate. + +## Get support from others in the community + +Disagreements, both political and technical, happen all the time. Our community is no exception to the rule. The goal is not to avoid disagreements or differing views but to resolve them constructively. You should turn to the community to seek advice and to resolve disagreements and where possible consult the team most directly involved. + +Think deeply before turning a disagreement into a public dispute. If necessary, request mediation, and try to resolve differences in a less emotional medium. If you do feel that you or your work is being attacked, take your time to think things through before writing heated replies. Consider a 24-hour moratorium if emotional language is being used – a cooling-off period is sometimes all that is needed. If you really want to go a different way, then we encourage you to publish your ideas and your work, so that it can be tried and tested. + +This work, "IOTA Community Guidelines", is a derivative of the [Community code of conduct by ownCloud](https://owncloud.org/community/code-of-conduct/), used under [CC BY-SA 3.0](https://creativecommons.org/licenses/by-sa/3.0/). "IOTA Community Guidelines" is licensed under [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) by IOTA Foundation. \ No newline at end of file diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..30b2aba --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,154 @@ +# Contribute to the Python client library + +This document describes how to contribute to the Python client library. + +We encourage everyone with knowledge of IOTA technology to contribute. + +Thanks! :heart: + +
+Do you have a question :question: +
+ +If you have a general or technical question, you can use one of the following resources instead of submitting an issue: + +- [**Developer documentation:**](https://docs.iota.org/) For official information about developing with IOTA technology +- [**Discord:**](https://discord.iota.org/) For real-time chats with the developers and community members +- [**IOTA cafe:**](https://iota.cafe/) For technical discussions with the Research and Development Department at the IOTA Foundation +- [**StackExchange:**](https://iota.stackexchange.com/) For technical and troubleshooting questions +
+ +
+ +
+Ways to contribute :mag: +
+ +To contribute to the Python client library on GitHub, you can: + +- Report a bug +- Suggest a new feature +- Build a new feature +- Contribute to the documentation +
+ +
+ +
+Report a bug :bug: +
+ +This section guides you through reporting a bug. Following these guidelines helps maintainers and the community understand the bug, reproduce the behavior, and find related bugs. + +### Before reporting a bug + +Please check the following list: + +- **Do not open a GitHub issue for [security vulnerabilities](SECURITY.MD)**, instead, please contact us at [security@iota.org](mailto:security@iota.org). + +- **Ensure the bug was not already reported** by searching on GitHub under [**Issues**](https://github.com/iotaledger/iota.py/issues). If the bug has already been reported **and the issue is still open**, add a comment to the existing issue instead of opening a new one. You can also find related issues by their [label](https://github.com/iotaledger/iota.py/labels?page=1&sort=name-asc). + +**Note:** If you find a **Closed** issue that seems similar to what you're experiencing, open a new issue and include a link to the original issue in the body of your new one. + +### Submitting A Bug Report + +To report a bug, [open a new issue](https://github.com/iotaledger/iota.py/issues/new), and be sure to include as many details as possible, using the template. + +**Note:** Minor changes such as fixing a typo can but do not need an open issue. + +If you also want to fix the bug, submit a [pull request](#pull-requests) and reference the issue. +
+ +
+ +
+Suggest a new feature :bulb: +
+ +This section guides you through suggesting a new feature. Following these guidelines helps maintainers and the community collaborate to find the best possible way forward with your suggestion. + +### Before suggesting a new feature + +**Ensure the feature has not already been suggested** by searching on GitHub under [**Issues**](https://github.com/iotaledger/iota.py/issues). + +### Suggesting a new feature + +To suggest a new feature, talk to the IOTA community and IOTA Foundation members on [Discord](https://discord.iota.org/). + +If the team members approve your feature, they will create an issue for it. +
+ +
+ +
+Build a new feature :hammer: +
+ +This section guides you through building a new feature. Following these guidelines helps give your feature the best chance of being approved and merged. + +### Before building a new feature + +Make sure to discuss the feature with the developers on [Discord](https://discord.iota.org/). + +Otherwise, your feature may not be approved at all. + +### Building a new feature + +To build a new feature, check out a new branch based on the `develop` branch, and be sure to consider the following: + +- If the feature will become part of PyOTA's public interface (i.e., it includes methods that will be invoked by other developers in their applications), make sure to document it, using [Sphinx-style](https://www.sphinx-doc.org/en/master/) code comments. + +
+ +
+ +
+Contribute to the documentation :black_nib: +
+ +The Python client library documentation is hosted on https://docs.iota.org, which is built from content in the [documentation](https://github.com/iotaledger/documentation) repository. + +Please see the [guidelines](https://github.com/iotaledger/documentation/CONTRIBUTING.md) on the documentation repository for information on how to contribute to the documentation. +
+ +
+ +
+Pull requests :mega: +
+ +This section guides you through submitting a pull request (PR). Following these guidelines helps give your PR the best chance of being approved and merged. + +### Before submitting a pull request + +When creating a pull request, please follow these steps to have your contribution considered by the maintainers: + +- A pull request should have only one concern (for example one feature or one bug). If a PR addresses more than one concern, it should be split into two or more PRs. + +- A pull request can be merged only if it references an open issue. + + **Note:** Minor changes such as fixing a typo can but do not need an open issue. + +- All code should include comprehensive unit tests. + +### Submitting a pull request + +The following is a typical workflow for submitting a new pull request: + +1. Fork this repository +2. Create a new branch based on your fork +3. Commit changes and push them to your fork +4. Create a pull request against the `develop` branch + +If all [status checks](https://help.github.com/articles/about-status-checks/) pass, and the maintainer approves the PR, it will be merged. + +**Note:** Reviewers may request changes before your pull request can be approved and merged. +
+ +
+ +
+Code of Conduct :clipboard: +
+ +This project and everyone participating in it are governed by the [IOTA Code of Conduct](CODE_OF_CONDUCT.md). diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..2607ec9 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,48 @@ +--- +name: Report a bug in the Python client library +about: Report a bug +labels: bug +--- + +## Bug description + +Briefly describe the bug. + +## Version + +Which version of the library are you running? + +- PyOTA Version: +- Python Version: + +## IOTA network + +Which node are you connected to and which IOTA network is it in? + +- Node URL: +- Network: + +## Environment + +What operating system are you using? + +- Operating system: +## Steps To reproduce the bug + +Explain how the maintainer can reproduce the bug. + +1. +2. +3. + +## Expected behaviour + +Describe what you expect to happen. + +## Actual behaviour + +Describe what actually happens. + +## Errors + +Paste here any error messages and/or stacktraces that you see. diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..596e17a --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Discord + url: https://discord.iota.org/ + about: Please ask and answer questions here. + - name: Security vulnerabilities + url: security@iota.org + about: Please report security vulnerabilities here. \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..f94bd08 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,28 @@ +--- +name: Request a feature for the Python client library +about: Request a feature +--- + +## Description + +Briefly describe the feature that you are requesting. + +## Motivation + +Explain why this feature is needed. + +## Requirements + +Write a list of what you want this feature to do. + +1. +2. +3. + +## Open questions (optional) + +Use this section to ask any questions that are related to the feature. + +## Are you planning to do it yourself in a pull request? + +Yes/No. diff --git a/.github/SECURITY.md b/.github/SECURITY.md new file mode 100644 index 0000000..a272f5d --- /dev/null +++ b/.github/SECURITY.md @@ -0,0 +1,22 @@ +

Responsible disclosure policy

+ +At the IOTA Foundation, we consider the security of our systems a top priority. But no matter how much effort we put into system security, there can still be vulnerabilities present. If you've discovered a vulnerability, please follow the guidelines below to report it to our security team: + +Please follow these rules when testing/reporting vulnerabilities: + +What we promise: + +We sincerely appreciate the efforts of security researchers in keeping our community safe. diff --git a/.github/SUPPORT.md b/.github/SUPPORT.md new file mode 100644 index 0000000..7f052de --- /dev/null +++ b/.github/SUPPORT.md @@ -0,0 +1,8 @@ +# Community resources + +If you have a general or technical question, you can use one of the following resources instead of submitting an issue: + +- [**Developer documentation:**](https://docs.iota.org/) For official information about developing with IOTA technology +- [**Discord:**](https://discord.iota.org/) For real-time chats with the developers and community members +- [**IOTA cafe:**](https://iota.cafe/) For technical discussions with the Research and Development Department at the IOTA Foundation +- [**StackExchange:**](https://iota.stackexchange.com/) For technical and troubleshooting questions \ No newline at end of file diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..d127d30 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,29 @@ +# Description of change + +Please write a summary of your changes and why you made them. Be sure to reference any related issues by adding `fixes # (issue)`. + +## Type of change + +Choose a type of change, and delete any options that are not relevant. + +- Bug fix (a non-breaking change which fixes an issue) +- Enhancement (a non-breaking change which adds functionality) +- Breaking change (fix or feature that would cause existing functionality to not work as expected) +- Documentation Fix + +## How the change has been tested + +Describe the tests that you ran to verify your changes. + +Make sure to provide instructions for the maintainer as well as any relevant configurations. + +## Change checklist + +Add an `x` to the boxes that are relevant to your changes, and delete any items that are not. + +- [ ] My code follows the contribution guidelines for this project +- [ ] I have performed a self-review of my own code +- [ ] I have commented my code, particularly in hard-to-understand areas +- [ ] I have made corresponding changes to the documentation (`docs/` directory and/or `docstring`s in source code) +- [ ] I have followed [PEP-8](https://www.python.org/dev/peps/pep-0008/) Style Guide in my code. +- [ ] New and existing unit tests pass locally with my changes diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst deleted file mode 100644 index 9642866..0000000 --- a/CONTRIBUTING.rst +++ /dev/null @@ -1,167 +0,0 @@ -===================== -Contributing to PyOTA -===================== -So, you wanna contribute to PyOTA? Awesome! PyOTA is an important part of the IOTA ecosystem, and it's all thanks to people like you! - -PyOTA is largely built and maintained by volunteers; by following a few "common sense" ground rules, we can make PyOTA stand out as a fun, exciting and rewarding project to work on. - -Please take a few moments to read this guide to familiarize yourself with PyOTA's contributor code of conduct, and some of the ways you can contribute! - -.. contents:: - :depth: 2 - - -Ways You Can Help! -================== -There are lots of ways to get involved with PyOTA. Many of them don't require writing any code (but if that's your thing, we've got you covered, too!). - -- Improving Documentation -- Writing Tutorials -- Reporting Bugs -- Helping Users on the ``#python`` Channel on `Discord`_ -- Fixing Bugs and Implementing New Features -- Writing Unit and Functional Tests - -A Few Things that We Can't Accept ---------------------------------- -We're pretty open about how people contribute to PyOTA, but there are a few things that we can't accept: - -- Please do not post support requests here. Use the ``#python`` channel on `Discord`_ -- Please do not propose new API methods here. There are multiple IOTA API libraries out there, and they must all have the same functionality. - - - That said, if you have an idea for a new API method, please share it on the ``#clients-discussion`` channel in `Discord`_ so that IOTA Foundation members can evaluate it! - - -Need Some Inspiration? -====================== -If you would like to help out but don't know how to get started, here are some -places you can look for inspiration: - -- Look for issues marked `help wanted`_ in the `PyOTA Bug Tracker`_ -- Introduce yourself in the `#python` channel in `Discord`_ and watch for questions or issues that you can help with. -- Browse existing `tutorials`_ for other programming languages and create Python versions. - -Is This Your First Contribution? --------------------------------- -Never contributed to an open-source project before? No problem! We're excited that you are considering PyOTA for your first contribution! - -Please take a few minutes to read GitHub's guide on `How to Contribute to Open Source`_. It's a quick read, and it's a great way to introduce yourself to how things work behind the scenes in open-source projects. - - -Guidelines for Reporting Bugs -============================= -Found a bug in the PyOTA code? Great! We can't fix bugs we don't know about; your bug report will go a long way toward helping PyOTA flourish. - -Instructions ------------- -1. Make sure it really is a PyOTA bug. - - - Check the traceback, and see if you can narrow down the cause of the bug. - - If the error is not directly caused by PyOTA, or if you are unable to figure out what is causing the problem, we're still here for for you! Post in the ``#python`` channel in `Discord`_ for assistance. - -2. Is it safe to publish details about this bug publicly? - - - If the bug is security-related (e.g., could compromise a user's seed if exploited), or if it requires sensitive information in order to reproduce (e.g., the private key for an address), please do not post in in the PyOTA Bug Tracker! - - To report security-related bugs, please contact ``@phx`` directly in `Discord`_. - -3. Is this a known issue? - - - Before posting a bug report, check the `PyOTA Bug Tracker`_ to see if there is an existing issue for this bug. - -4. Create a new issue in the `PyOTA Bug Tracker`_. - - - Be sure to include the following information: - - - Which version of PyOTA you are using. - - Which version of Python you are using. - - Which operating system you are using. - - Instructions to reproduce the bug. - - The expected behavior, if applicable. - - The full exception traceback, if available. - - If the exception also has a context object, please include it. - -5. Please be nice! - - - It's frustrating when things don't work the way you expect them to. We promise we didn't put that bug in there on purpose; we're all human, and we all make mistakes sometimes. - -6. Please be patient! - - - We're committed to making to making PyOTA better, but we've also got jobs and other commitments. We'll respond as soon as we can, but it might be a few days. - -7. Please be responsive if follow-up is needed. - - - We may request additional information to help us identify/fix the bug. The faster you respond to follow-up comments in your bug report, the sooner we can squash that bug! - - If someone adds a comment to your bug report, it will appear in the `Notifications`_ page in GitHub. You can also configure GitHub to `email you`_ when a new comment is posted. - -What You Can Expect -------------------- -When you submit a bug report, here's what you can expect from the individual who reviews it: - -- You can expect a response within one week of submission. -- If any additional information is needed, or if we are having trouble reproducing the issue you reported, you can expect a respectful and constructive response. - - -Guidelines for Developers -========================= -If you would like to contribute code to the PyOTA project, this section is for you! - -Instructions ------------- -1. Find an issue in the `PyOTA Bug Tracker`_ to work on. - - - If you want to work on a bug or feature that doesn't have a GitHub issue yet, create a new one before starting to work on it. That will give other developers an opportunity to provide feedback and/or suggest changes that will make it integrate better with the rest of the code. - -2. Create a fork of the PyOTA repository. -3. Create a new branch just for the bug/feature you are working on. - - - If you want to work on multiple bugs/features, you can use branches to keep them separate, so that you can submit a separate Pull Request for each one. - -4. Once you have completed your work, create a Pull Request, ensuring that it meets the requirements listed below. - -Requirements for Pull Requests ------------------------------- -PyOTA is a critical component for many applications, and as such its code must be of exceptionally high quality. To help maintain reliability and code quality, there are a few requirements for contributions. - -This is a big list, but don't let it intimidate you! Many of these are "common sense" things that you probably do already, but we have to list them here anyway, just so that there's no confusion. - -If you have any questions, please feel free to post in the ``#python`` channel in `Discord`_! - -- Please create Pull Requests against the ``develop`` branch. -- Please limit each Pull Request to a single bugfix/enhancement. -- Please limit the scope of each Pull Request to just the changes needed for that bugfix/enhancement. - - - If you would like to refactor existing code, please create separate Pull Request(s) just for the refactoring. - -- Please ensure your code works in all supported versions of Python (this includes versions of Python 2 and Python 3). - - - See ``README.rst`` for the list of supported Python versions. - -- Please ensure that your Pull Request includes full test coverage. -- Please do not introduce new dependencies unless absolutely necessary. -- When introducing new classes/functions, please write comprehensive and meaningful docstrings. It should be clear to anyone reading your code what your new class/function does and why it exists. - - Similarly, please be liberal about adding comments to your code. If you have any knowledge and/or had to do any research that would make your code easier to understand, add it as comment. Future developers will be very grateful for the extra context! - - - Please ensure that your comments and docstrings use proper English grammar and spelling. - -- Please ensure that your code conforms to `PEP-8`_. - - - Much of the existing code is not currently formatted for PEP-8; where practical, you may prefer PEP-8 over being consistent with the existing code. - - We are currently converting the codebase over to PEP-8; `come on over and help us out!`_ - -What You Can Expect -------------------- -When you submit a Pull Request, here is what you can expect from the individual who reviews it: - -- You can expect a response within one week of submission. -- If any changes are needed, or if we cannot accept your submission, we will provide a respectful and constructive explanation. - - -.. _come on over and help us out!: https://github.com/iotaledger/iota.py/issues/145 -.. _email you: https://help.github.com/articles/managing-notification-delivery-methods/ -.. _help wanted: https://github.com/iotaledger/iota.py/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22 -.. _how to contribute to open source: https://opensource.guide/how-to-contribute/ -.. _notifications: https://github.com/notifications -.. _pep-8: https://www.python.org/dev/peps/pep-0008/ -.. _pyota bug tracker: https://github.com/iotaledger/iota.py/issues -.. _discord: https://discord.iota.org -.. _tutorials: https://docs.iota.org diff --git a/README.md b/README.md index 390e9a5..e1cfa1c 100644 --- a/README.md +++ b/README.md @@ -149,8 +149,9 @@ print(result['bundle'].hash) ## Supporting the project -If the IOTA Python client library has been useful to you and you feel like contributing, consider posting a [bug report](https://github.com/iotaledger/iota.py/issues/new-issue), feature request or a [pull request](https://github.com/iotaledger/iota.py/pulls/). -We have some [basic contribution guidelines](CONTRIBUTING.rst) to keep our code base stable and consistent. +If the IOTA Python client library has been useful to you and you feel like contributing, consider posting a [bug report](https://github.com/iotaledger/iota.py/issues/new-issue), feature request or a [pull request](https://github.com/iotaledger/iota.py/pulls/). + +We have some [basic contribution guidelines](.github/CONTRIBUTING.md) to keep our code base stable and consistent. ### Running test cases @@ -173,9 +174,9 @@ pip install -e .[test-runner] tox -v -p all ``` -### Building the auto-generated documentation +### Building the autogenerated documentation -The auto-generated documentation can be generated on your local device by doing the following: +The autogenerated documentation can be generated on your local device by doing the following: ```bash # Install extra dependencies (you only have to do this once) @@ -187,4 +188,4 @@ make html ## Joining the discussion -If you want to get involved in the community, need help with getting setup, have any issues related with the library or just want to discuss blockchain, distributed ledgers, and IoT with other people, feel free to join our [Discord](https://discord.iota.org/). +If you want to get involved in the community, need help with getting set up, have any issues related with the library or just want to discuss blockchain, distributed ledgers, and IoT with other people, feel free to join our [Discord](https://discord.iota.org/). diff --git a/docs/commands.rst b/docs/commands.rst index a3a5771..cd32985 100644 --- a/docs/commands.rst +++ b/docs/commands.rst @@ -214,4 +214,4 @@ it constructs a list of transaction objects that are returned to .. _filters documentation site: https://filters.readthedocs.io/en/latest/ .. _create custom filters: https://filters.readthedocs.io/en/latest/writing_filters.html .. _PyOTA Bug Tracker: https://github.com/iotaledger/iota.py/issues -.. _Contributing to PyOTA: https://github.com/iotaledger/iota.py/blob/master/CONTRIBUTING.rst \ No newline at end of file +.. _Contributing to PyOTA: https://github.com/iotaledger/iota.py/blob/master/.github/CONTRIBUTING.md \ No newline at end of file