From c9a77e62d5c3820628d9d6bcd0a98839f785a749 Mon Sep 17 00:00:00 2001
From: Hugo Slepicka
Date: Tue, 30 Oct 2018 17:27:53 -0700
Subject: [PATCH] DOC: Improve README.md, add GitHub issues templates,
contributing guidelines and support.
---
.github/CONTRIBUTING.md | 77 +++++++++++++++++++++++
.github/ISSUE_TEMPLATE/bug-report.md | 31 +++++++++
.github/ISSUE_TEMPLATE/feature-request.md | 14 +++++
.github/SUPPORT.md | 25 ++++++++
README.md | 26 ++++++--
setup.py | 7 ++-
6 files changed, 174 insertions(+), 6 deletions(-)
create mode 100644 .github/CONTRIBUTING.md
create mode 100644 .github/ISSUE_TEMPLATE/bug-report.md
create mode 100644 .github/ISSUE_TEMPLATE/feature-request.md
create mode 100644 .github/SUPPORT.md
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
new file mode 100644
index 000000000..d08cbc875
--- /dev/null
+++ 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..
+
+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
\ No newline at end of file
diff --git a/.github/ISSUE_TEMPLATE/bug-report.md b/.github/ISSUE_TEMPLATE/bug-report.md
new file mode 100644
index 000000000..3d1bd8324
--- /dev/null
+++ 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**
+
+
+**Expected behavior**
+
+
+**Steps to Reproduce**
+
+
+**Possible Solution**
+
+
+**My Platform**
+
+
+**Additional context**
+
diff --git a/.github/ISSUE_TEMPLATE/feature-request.md b/.github/ISSUE_TEMPLATE/feature-request.md
new file mode 100644
index 000000000..2c6476c29
--- /dev/null
+++ 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?**
+
+
+**Describe the solution you'd like**
+
+
+**Additional context**
+
diff --git a/.github/SUPPORT.md b/.github/SUPPORT.md
new file mode 100644
index 000000000..89c4e0587
--- /dev/null
+++ 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]() (Public)
+- Stanford & SLAC [Slack channel]() (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.
\ No newline at end of file
diff --git a/README.md b/README.md
index c9157dfe4..5c2bc142b 100644
--- 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)
+
+
PyDM: Python Display Manager
-# 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.
+
+ 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.
+
+
+ « Explore PyDM docs and tutorials »
+
+
+ Report bug
+ ·
+ Request feature
+ ·
+ How to Contribute
+ ·
+ Support
+
+
+
+
# Python Qt Wrapper
PyDM project uses the [qtpy](https://github.com/spyder-ide/qtpy)
diff --git a/setup.py b/setup.py
index 0bde9c8a9..1d179645c 100644
--- 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'