DOC: Improve README.md, add GitHub issues templates, contributing gui…

…delines and support.
slaclab · Oct 31, 2018 · c9a77e6 · c9a77e6
1 parent cd4f79a
commit c9a77e6
Show file tree

Hide file tree

Showing 6 changed files with 174 additions and 6 deletions.
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -0,0 +1,77 @@
+# Contributing
+
+## Getting Started
+
+* Make sure you have a [GitHub account](https://github.com/signup/free)
+* Submit a ticket for your issue, assuming one does not already exist.
+  * Clearly describe the issue including steps to reproduce when it is a bug.
+  * Make sure you fill in the earliest version that you know has the issue.
+* Fork the repository on GitHub
+
+
+## Making Changes
+
+* Create a topic branch from where you want to base your work.
+  * This is usually the master branch.
+  * Only target release branches if you are certain your fix must be on that
+    branch.
+  * To quickly create a topic branch based on master; `git checkout -b
+    fix/master/my_contribution master`. Please avoid working directly on the
+    `master` branch.
+* Make commits of logical units.
+* Check for unnecessary whitespace with `git diff --check` before committing.
+* Make sure your commit messages are in the proper format (see below)
+* Make sure you have added the necessary tests for your changes.
+* Run _all_ the tests to assure nothing else was accidentally broken.
+
+### Writing the commit message
+
+Commit messages should be clear and follow a few basic rules. Example:
+
+```
+ENH: add functionality X to pydm.<submodule>.
+
+The first line of the commit message starts with a capitalized acronym
+(options listed below) indicating what type of commit this is.  Then a blank
+line, then more text if needed.  Lines shouldn't be longer than 72
+characters.  If the commit is related to a ticket, indicate that with
+"See #3456", "See ticket 3456", "Closes #3456" or similar.
+```
+
+Describing the motivation for a change, the nature of a bug for bug fixes 
+or some details on what an enhancement does are also good to include in a 
+commit message. Messages should be understandable without looking at the code 
+changes. 
+
+Standard acronyms to start the commit message with are:
+
+
+|Code| Description                                        |
+|----|----------------------------------------------------|
+|API | an (incompatible) API change                       |
+|BLD | change related to building                         |
+|BUG | bug fix                                            |
+|DEP | deprecate something, or remove a deprecated object |
+|DEV | development tool or utility                        |
+|DOC | documentation                                      |
+|ENH | enhancement                                        |
+|MNT | maintenance commit (refactoring, typos, etc.)      |
+|REV | revert an earlier commit                           |
+|STY | style fix (whitespace, PEP8)                       |
+|TST | addition or modification of tests                  |
+|REL | related to releasing numpy                         |
+|WIP | Commit that is a work in progress                  |
+
+## The Pull Request
+
+* Now push to your fork
+* Submit a [pull request](https://help.github.com/articles/using-pull-requests) to this branch. This is a start to the conversation.
+
+At this point you're waiting on us. We like to at least comment on pull requests within three business days 
+(and, typically, one business day). We may suggest some changes or improvements or alternatives.
+
+Hints to make the integration of your changes easy (and happen faster):
+- Keep your pull requests small
+- Don't forget your unit tests
+- All algorithms need documentation, don't forget the .rst file
+- Don't take changes requests to change your code personally
diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md
@@ -0,0 +1,31 @@
+---
+name: Bug report
+about: Let us know if something is broken on PyDM.
+
+---
+
+**Describe the bug**
+<!-- A clear and concise description the bug -->
+
+**Expected behavior**
+<!-- A clear and concise description of what you expected to happen -->
+
+**Steps to Reproduce**
+<!-- Steps to reproduce the bug -->
+
+**Possible Solution**
+<!--
+    Not obligatory, but suggest a fix/reason for the bug, or ideas how to 
+    implement the addition or change.
+--> 
+
+**My Platform**
+<!--
+    Any details about your specific platform:
+    * OS Version
+    * Python Version
+    * Packages Version (One good start point is the File > About screen at PyDM.
+-->
+
+**Additional context**
+<!-- Add any other context, links, etc. about the bug here. -->
diff --git a/.github/ISSUE_TEMPLATE/feature-request.md b/.github/ISSUE_TEMPLATE/feature-request.md
@@ -0,0 +1,14 @@
+---
+name: Feature request
+about: Suggest a new feature for PyDM
+
+---
+
+**What's the problem this feature will solve?**
+<!-- A clear and concise description of what the problem is. -->
+
+**Describe the solution you'd like**
+<!-- A clear and concise description of what you want to happen. -->
+
+**Additional context**
+<!-- Add any other context, links, etc. about the feature here. -->
diff --git a/.github/SUPPORT.md b/.github/SUPPORT.md
@@ -0,0 +1,25 @@
+### Getting Started
+
+PyDM offers a great step-by-step [tutorial](https://slaclab.github.io/pydm-tutorial)
+with detailed information to help you get started with creating displays and even
+more complex applications. 
+
+### Bug reports & Feature request
+
+If you spot a problem with PyDM, please let us know by following the template in
+here: [Report a bug](https://github.com/slaclab/pydm/issues/new?template=bug-report.md).
+
+Ideas or suggestions for enhancements are more than welcome. Please use the following
+template in here: [Request feature](https://github.com/slaclab/pydm/issues/new?template=feature-request.md).
+
+### Contact us
+
+If you have questions of comments in general about PyDM we want to know.
+
+You can choose between the channels open for communication the one that best fit you:
+
+- Chat channel using [Gitter](<https://gitter.im/pydm/General>) (Public)
+- Stanford & SLAC [Slack channel](<https://slac.slack.com/messages/C6B8GRCPQ>) (Limited for users with a Stanford Account)
+- PyDM [Mailing List](https://listserv.slac.stanford.edu/cgi-bin/wa?SUBED1=PYDM-USERS) (Limited for SLAC users for now)
+
+or you can [file a bug](https://github.com/slaclab/pydm/issues/new?template=bug-report.md) and let us know where our documentation could be improved.
diff --git a/README.md b/README.md
@@ -3,11 +3,29 @@
 [![Code Health](https://landscape.io/github/slaclab/pydm/master/landscape.svg?style=flat)](https://landscape.io/github/slaclab/pydm/master) 
 [![codecov](https://codecov.io/gh/slaclab/pydm/branch/master/graph/badge.svg)](https://codecov.io/gh/slaclab/pydm)
 
+<p align="center">
+  <h1 align="center">PyDM: Python Display Manager</h1>
 
-# pydm: Python Display Manager
-pydm is a PyQt-based framework for building user interfaces for control systems.
-The goal is to provide a no-code, drag-and-drop system to make simple screens,
-as well as a straightforward Python framework to build complex applications.
+  <p align="center">
+    PyDM is a PyQt-based framework for building user interfaces for control systems.
+    The goal is to provide a no-code, drag-and-drop system to make simple screens,
+    as well as a straightforward Python framework to build complex applications.
+    <br>
+    <br>
+    <strong>« Explore PyDM <a href="https://slaclab.github.io/pydm/">docs</a> and <a href="https://slaclab.github.io/pydm-tutorial">tutorials</a> »</strong>
+    <br>
+    <br>
+    <a href="https://github.com/slaclab/pydm/issues/new?template=bug-report.md">Report bug</a>
+    ·
+    <a href="https://github.com/slaclab/pydm/issues/new?template=feature-request.md&labels=request">Request feature</a>
+    ·
+    <a href="https://github.com/slaclab/pydm/blob/master/.github/CONTRIBUTING.md">How to Contribute</a>
+    ·
+    <a href="https://github.com/slaclab/pydm/blob/master/.github/SUPPORT.md">Support</a>
+  </p>
+</p>
+
+<br>
 
 # Python Qt Wrapper
 PyDM project uses the [qtpy](https://github.com/spyder-ide/qtpy)

diff --git a/setup.py b/setup.py
@@ -10,6 +10,9 @@
 with open(path.join(cur_dir, 'requirements.txt')) as f:
     requirements = f.read().split()
 
+with open(path.join(cur_dir, 'README.md')) as f:
+    long_description = f.read()
+
 # Remove the 'optional' requirements
 optional = ('PyQt5', 'PySide', 'psutil', 'pcaspy', 'pyepics')
 for package in optional:
@@ -51,9 +54,9 @@
     packages=find_packages(),
     package_dir={'pydm':'pydm', 'pydm_launcher':'pydm_launcher'},
     description='Python Display Manager',
+    long_description=long_description,
+    long_description_content_type='text/markdown',
     url='https://github.com/slaclab/pydm',
-    # scripts=['scripts/pydm', 'scripts/pydm-testing-ioc'],
-    # package_data={'pydm': ['data/access_rules.as']},
     entry_points={
         'gui_scripts': [
             'pydm=pydm_launcher.main:main'