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'