project structure and packaging revamp

* deleted top level `__init__.py` - its not part of the default code structure * improved `setup.py`: - DRYed up `install_requires` by allowing `requirements.txt` to just read from here - gave dependencies version ranges - added `long_description` property - changed `url` property to an https one - changed `author` and `author_email` property to reflect the entire company - added `classifiers` property - added `keywords` property - remove `zip_safe` property * specified `flake8` configuration in `.flake8` * added support for py33 (its not EOL until sept 2017) * modified travis build - use travis' own virtualenv switching system instead of relying on tox to do it - fail earlier if lint does not succeed - moved `coverage` tool configuration to `.coveragerc` * enabled binary distribution as a universal wheel (python2 and python3) * removed unncessary test dependencies * simplified and commented `tox.ini` - implemented docs generation as a tox task * remove single underscore for all filenames inside `slackclient/` (except `__init__.py`) * change `slackclient/__init__.py` to `from .client import SlackClient` * badges for python version support * get CI for windows (AppVeyor) * added new oss-guidelines
slackapi · Jun 21, 2017 · 395faff · 395faff
1 parent f8ebd4a
commit 395faff
Show file tree

Hide file tree

Showing 87 changed files with 5,728 additions and 4,846 deletions.
diff --git a/.appveyor.yml b/.appveyor.yml
@@ -0,0 +1,40 @@
+# credit: https://packaging.python.org/guides/supporting-windows-using-appveyor/
+
+environment:
+  matrix:
+    - PYTHON: "C:\\Python27"
+      PYTHON_VERSION: "py27-x86"
+    - PYTHON: "C:\\Python33"
+      PYTHON_VERSION: "py33-x86"
+    - PYTHON: "C:\\Python34"
+      PYTHON_VERSION: "py34-x86"
+    - PYTHON: "C:\\Python35"
+      PYTHON_VERSION: "py35-x86"
+    - PYTHON: "C:\\Python36"
+      PYTHON_VERSION: "py36-x86"
+    - PYTHON: "C:\\Python27-x64"
+      PYTHON_VERSION: "py27-x64"
+    - PYTHON: "C:\\Python33-x64"
+      PYTHON_VERSION: "py33-x64"
+    - PYTHON: "C:\\Python34-x64"
+      PYTHON_VERSION: "py34-x64"
+    - PYTHON: "C:\\Python35-x64"
+      PYTHON_VERSION: "py35-x64"
+    - PYTHON: "C:\\Python36-x64"
+      PYTHON_VERSION: "py36-x64"
+
+install:
+  - "%PYTHON%\\python.exe -m pip install wheel"
+  - "%PYTHON%\\python.exe -m pip install -r requirements.txt"
+  - "%PYTHON%\\python.exe -m pip install flake8"
+  - "%PYTHON%\\python.exe -m pip install -r test_requirements.txt"
+
+build: off
+
+test_script:
+  - "%PYTHON%\\python.exe -m flake8 slackclient"
+  - "%PYTHON%\\python.exe -m py.test --cov-report= --cov=slackclient tests"
+
+# maybe `after_test:`?
+on_success:
+  - "%PYTHON%\\python.exe -m codecov -e win-%PYTHON_VERSION%"
diff --git a/.coveragerc b/.coveragerc
@@ -0,0 +1,13 @@
+[run]
+branch = True
+source = slackclient
+
+[report]
+exclude_lines =
+    if self.debug:
+    pragma: no cover
+    raise NotImplementedError
+    if __name__ == .__main__.:
+ignore_errors = True
+omit =
+    tests/*
diff --git a/.flake8 b/.flake8
@@ -0,0 +1,2 @@
+[flake8]
+max-line-length = 100
diff --git a/.github/contributing.md b/.github/contributing.md
@@ -0,0 +1,60 @@
+# Contributors Guide
+
+Interested in contributing? Awesome! Before you do though, please read our
+[Code of Conduct](https://slackhq.github.io/code-of-conduct). We take it very seriously, and expect that you will as
+well.
+
+There are many ways you can contribute! :heart:
+
+### Bug Reports and Fixes :bug:
+-  If you find a bug, please search for it in the [Issues](https://github.com/slackapi/python-slackclient/issues), and if it isn't already tracked,
+   [create a new issue](https://github.com/slackapi/python-slackclient/issues/new). Fill out the "Bug Report" section of the issue template. Even if an Issue is closed, feel free to comment and add details, it will still
+   be reviewed.
+-  Issues that have already been identified as a bug (note: able to reproduce) will be labelled `bug`.
+-  If you'd like to submit a fix for a bug, [send a Pull Request](#creating_a_pull_request) and mention the Issue number.
+  -  Include tests that isolate the bug and verifies that it was fixed.
+
+### New Features :bulb:
+-  If you'd like to add new functionality to this project, describe the problem you want to solve in a [new Issue](https://github.com/slackapi/python-slackclient/issues/new).
+-  Issues that have been identified as a feature request will be labelled `enhancement`.
+-  If you'd like to implement the new feature, please wait for feedback from the project
+   maintainers before spending too much time writing the code. In some cases, `enhancement`s may
+   not align well with the project objectives at the time.
+
+### Tests :mag:, Documentation :books:, Miscellaneous :sparkles:
+-  If you'd like to improve the tests, you want to make the documentation clearer, you have an
+   alternative implementation of something that may have advantages over the way its currently
+   done, or you have any other change, we would be happy to hear about it!
+  -  If its a trivial change, go ahead and [send a Pull Request](#creating_a_pull_request) with the changes you have in mind.
+  -  If not, [open an Issue](https://github.com/slackapi/python-slackclient/issues/new) to discuss the idea first.
+
+If you're new to our project and looking for some way to make your first contribution, look for
+Issues labelled `good first contribution`.
+
+## Requirements
+
+For your contribution to be accepted:
+
+- [x] You must have signed the [Contributor License Agreement (CLA)](https://cla-assistant.io/slackapi/python-slackclient).
+- [x] The test suite must be complete and pass.
+- [x] The changes must be approved by code review.
+- [x] Commits should be atomic and messages must be descriptive. Related issues should be mentioned by Issue number.
+
+If the contribution doesn't meet the above criteria, you may fail our automated checks or a maintainer will discuss it with you. You can continue to improve a Pull Request by adding commits to the branch from which the PR was created.
+
+[Interested in knowing more about about pull requests at Slack?](https://slack.engineering/on-empathy-pull-requests-979e4257d158#.awxtvmb2z)
+
+## Creating a Pull Request
+
+1.  :fork_and_knife: Fork the repository on GitHub.
+2.  :runner: Clone/fetch your fork to your local development machine. It's a good idea to run the tests just
+    to make sure everything is in order.
+3.  :herb: Create a new branch and check it out.
+4.  :crystal_ball: Make your changes and commit them locally. Magic happens here!
+5.  :arrow_heading_up: Push your new branch to your fork. (e.g. `git push username fix-issue-16`).
+6.  :inbox_tray: Open a Pull Request on github.com from your new branch on your fork to `master` in this
+    repository.
+
+## Maintainers
+
+There are more details about processes and workflow in the [Maintainer's Guide](./maintainers_guide.md).
diff --git a/.github/issue_template.md b/.github/issue_template.md
@@ -0,0 +1,48 @@
+### Description
+
+Describe your issue here.
+
+### What type of issue is this? (place an `x` in one of the `[ ]`)
+- [ ] bug
+- [ ] enhancement (feature request)
+- [ ] question
+- [ ] documentation related
+- [ ] testing related
+- [ ] discussion
+
+### Requirements (place an `x` in each of the `[ ]`)
+* [ ] I've read and understood the [Contributing guidelines](https://github.com/slackapi/python-slackclient/blob/master/.github/contributing.md) and have done my best effort to follow them.
+* [ ] I've read and agree to the [Code of Conduct](https://slackhq.github.io/code-of-conduct).
+* [ ] I've searched for any related issues and avoided creating a duplicate issue.
+
+---
+
+### Bug Report
+
+Filling out the following details about bugs will help us solve your issue sooner.
+
+#### Reproducible in:
+
+slackclient version:
+
+python version:
+
+OS version(s):
+
+#### Steps to reproduce:
+
+1.
+2.
+3.
+
+#### Expected result:
+
+What you expected to happen
+
+#### Actual result:
+
+What actually happened
+
+#### Attachments:
+
+Logs, screenshots, screencast, sample project, funny gif, etc.
diff --git a/.github/maintainers_guide.md b/.github/maintainers_guide.md
@@ -0,0 +1,100 @@
+# Maintainers Guide
+
+This document describes tools, tasks and workflow that one needs to be familiar with in order to effectively maintain
+this project. If you use this package within your own software as is but don't plan on modifying it, this guide is
+**not** for you.
+
+## Tools
+
+### Python (and friends)
+
+Not surprisingly, you will need to have Python installed on your system to work on this package. We support non-EOL,
+stable versions of CPython. The current supported versions are listed in the CI configurations (e.g. `.travis.yml`).
+At a minimum, you should have the latest version of Python 2 and the latest version of Python 3 to develop against.
+It's tricky to set up a system that has more than that, so you can lean on the CI servers to test changes on the
+in-between versions for you.
+
+You should also make sure you have the latest versions of `pip`, `setuptools`, `virtualenv`, `wheel`, `twine` and
+[`tox`](https://tox.readthedocs.io/en/latest/) installed with your version of Python.
+
+On macOS, the easiest way to install these tools is by using [Homebrew](https://brew.sh/) and installing the `python`
+and `python3` packages. Some of the above packages are preinstalled and you can install the remaining on your own:
+`pip install virtualenv wheel twine tox && pip3 install virtualenv twine tox`.
+
+## Tasks
+
+### Testing
+
+Tox is used to run the test suite across multiple isolated versions of Python. It is configured in `tox.ini` to
+run all the supported versions of Python, but when you invoke it, you should only select the versions you have on your
+system. For example, on a system with Python 2.7.13 and Python 3.6.1, you would run the tests using the following
+command: `tox -e flake8,py27,py36` (flake8 is a quality analysis tool).
+
+### Generating Documentation
+
+The documentation is generated from the source and templates in the `docs-src` directory. The generated documentation
+gets committed to the repo in `docs` and also published to a GitHub Pages website.
+
+You can generate the documentation by running `tox -e docs`.
+
+### Releasing
+
+1.  Create the commit for the release:
+    *  Bump the version number in adherence to [Semantic Versioning](http://semver.org/) in `slackclient/version.py`.
+    *  Commit with a message including the new version number. For example `1.0.6`.
+
+2.  Distribute the release
+    *  Build the distribtuions: `python setup.py sdist bdist_wheel`. This will create artifacts in the `dist` directory.
+    *  Publish to PyPI: `twine upload dist/*`. You must have access to the credentials to publish.
+    *  Create a GitHub Release. You will select the commit with updated version number (e.g. `1.0.6`) to assiociate with
+       the tag, and name the tag after this version (e.g. `1.0.6`). This will also serve as a Changelog for the project.
+       Add a description of changes to the Release. Mention Issue and PR #'s and @-mention contributors.
+
+3.  (Slack Internal) Communicate the release internally. Include a link to the GitHub Release.
+
+4.  Announce on Slack Team dev4slack in #slack-api
+
+5.  (Slack Internal) Tweet? Not necessary for patch updates, might be needed for minor updates, definitely needed for
+    major updates. Include a link to the GitHub Release.
+
+## Workflow
+
+### Versioning and Tags
+
+This project uses semantic versioning, expressed through the numbering scheme of
+[PEP-0440](https://www.python.org/dev/peps/pep-0440/).
+
+### Branches
+
+`master` is where active development occurs. Long running named feature branches are occasionally created for
+collaboration on a feature that has a large scope (because everyone cannot push commits to another person's open Pull
+Request). At some point in the future after a major version increment, there may be maintenance branches for older major
+versions.
+
+### Issue Management
+
+Labels are used to run issues through an organized workflow. Here are the basic definitions:
+
+*  `bug`: A confirmed bug report. A bug is considered confirmed when reproduction steps have been
+   documented and the issue has been reproduced.
+*  `enhancement`: A feature request for something this package might not already do.
+*  `docs`: An issue that is purely about documentation work.
+*  `tests`: An issue that is purely about testing work.
+*  `needs feedback`: An issue that may have claimed to be a bug but was not reproducible, or was otherwise missing some information.
+*  `discussion`: An issue that is purely meant to hold a discussion. Typically the maintainers are looking for feedback in this issues.
+*  `question`: An issue that is like a support request because the user's usage was not correct.
+*  `semver:major|minor|patch`: Metadata about how resolving this issue would affect the version number.
+*  `security`: An issue that has special consideration for security reasons.
+*  `good first contribution`: An issue that has a well-defined relatively-small scope, with clear expectations. It helps when the testing approach is also known.
+*  `duplicate`: An issue that is functionally the same as another issue. Apply this only if you've linked the other issue by number.
+
+**Triage** is the process of taking new issues that aren't yet "seen" and marking them with a basic level of information
+with labels. An issue should have **one** of the following labels applied: `bug`, `enhancement`, `question`,
+`needs feedback`, `docs`, `tests`, or `discussion`.
+
+Issues are closed when a resolution has been reached. If for any reason a closed issue seems relevant once again,
+reopening is great and better than creating a duplicate issue.
+
+## Everything else
+
+When in doubt, find the other maintainers and ask.
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,8 @@
+###  Summary
+
+Describe the goal of this PR. Mention any related Issue numbers.
+
+### Requirements (place an `x` in each `[ ]`)
+
+* [ ] I've read and understood the [Contributing Guidelines](https://github.com/slackapi/python-slackclient/blob/master/.github/contributing.md) and have done my best effort to follow them.
+* [ ] I've read and agree to the [Code of Conduct](https://slackhq.github.io/code-of-conduct).
diff --git a/.gitignore b/.gitignore
@@ -1,15 +1,21 @@
-*.pyc
-.cache
-.idea
-dist
-slackclient.egg-info
-*.log
-env
-.tox
-*.un~
-0/
-tests/.cache
+# general things to ignore
+build/
+dist/
+*.egg-info/
+*.egg
+*.py[cod]
+__pycache__/
+*.so
+*~
+
+# virtualenv
+env/
+venv/
+
+# codecov / coverage
 .coverage
-.cache
-.DS_Store
-.ropeproject
+cov_*
+
+# due to using tox and pytest
+.tox
+.cache
diff --git a/.travis.yml b/.travis.yml
@@ -2,19 +2,18 @@ sudo: false
 dist: trusty
 language: python
 python:
+  - "2.7"
+  - "3.3"
+  - "3.4"
+  - "3.5"
   - "3.6"
-env:
-  matrix:
-    - TOX_ENV=py27
-    - TOX_ENV=py34
-    - TOX_ENV=py35
-    - TOX_ENV=py36
-    - TOX_ENV=flake8
 cache: pip
 install:
-  - "travis_retry pip install setuptools --upgrade"
-  - "travis_retry pip install tox"
+  - travis_retry pip install -r requirements.txt
+  - travis_retry pip install flake8
+  - travis_retry pip install -r test_requirements.txt
 script:
-  - tox -e $TOX_ENV
-after_script:
-  - cat .tox/$TOX_ENV/log/*.log
+  - flake8 slackclient
+  - py.test --cov-report= --cov=slackclient tests
+after_success:
+  - codecov -e $TRAVIS_PYTHON_VERSION
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -0,0 +1,5 @@
+// Place your settings in this file to overwrite default and user settings.
+{
+  "python.linting.pylintEnabled": false,
+  "python.linting.flake8Enabled": true
+}
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md