From 9426c8f76a999b3293652d11512e44186053efc8 Mon Sep 17 00:00:00 2001 From: nstelter-slac Date: Tue, 3 Dec 2024 00:31:56 -0800 Subject: [PATCH] DOC: improve contributing docs, make nicer to read and add explicit setup instructions. Giving credit to https://github.com/pcdshub/happi/blob/master/CONTRIBUTING.rst, where most of the content is copied from. This new doc takes the relevant info from pydm's original page and applies it to happi's page (which imo is a more useful page) --- CONTRIBUTING.md | 143 ++++++++++++++++++++++++++++++++++++------------ 1 file changed, 107 insertions(+), 36 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d08cbc875..847a44186 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,30 +1,115 @@ -# Contributing +============ +Contributing +============ -## Getting Started +Contributions are welcome, and they are greatly appreciated! Every little bit +helps, and credit will always be given. -* 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 +You can contribute in many ways: +Types of Contributions +---------------------- -## Making Changes +Report Bugs +~~~~~~~~~~~ -* 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. +Report bugs at https://github.com/slaclab/pydm/issues. -### Writing the commit message +If you are reporting a bug, please try to include: + +* Any details about your local setup that might be helpful in troubleshooting. +* Detailed steps to reproduce the bug, including the earliest version you know has the issue. + +Fix Bugs +~~~~~~~~ + +Look through the GitHub issues for bugs. Anything tagged with "bug" +is open to whoever wants to implement it. + +Implement Features +~~~~~~~~~~~~~~~~~~ + +Look through the GitHub issues for features. Anything tagged with "feature" +is open to whoever wants to implement it. + +Write Documentation +~~~~~~~~~~~~~~~~~~~ + +pydm could always use more documentation, whether +as part of the official docs, in docstrings, +or even on the web in blog posts, articles, and such. + +Submit Feedback +~~~~~~~~~~~~~~~ + +The best way to send feedback is to file an issue at https://github.com/slaclab/pydm/issues. + +If you are proposing a feature: + +* Explain in detail how it would work. +* Keep the scope as narrow as possible, to make it easier to implement. +* Remember that this is a volunteer-driven project, and that contributions + are welcome :) + +Get Started! +------------ + +Ready to contribute? Here's how to set up `pydm` for local development. + +1. Fork the `pydm` repo on GitHub. +2. Clone your fork locally:: + + $ git clone git@github.com:your_username_here/pydm.git + +3. Install your local copy into a new conda environment. Assuming you have conda installed, this is how you set up your fork for local development:: + + $ conda create -n pydm-environment python=3.8 pyqt=5.12.3 pip numpy scipy six psutil pyqtgraph -c conda-forge + $ cd pydm/ + $ pip install -e . + +4. Install additional packages only needed for development and building the docs:: + + $ pip install -r dev-requirements.txt + $ pip install -r docs-requirements.txt + +5. Create a branch for local development:: + + $ git checkout -b name-of-your-bugfix-or-feature + + Now you can make your changes locally. + +6. Install and enable ``pre-commit`` for this repository:: + + $ pip install pre-commit + $ pre-commit install + +7. Add new tests for any additional functionality or bugs you may have discovered. And, of course, be sure that all previous tests still pass by running:: + + $ python run_tests.py + +8. Commit your changes and push your branch to GitHub:: + + $ git add . + $ git commit -m "Your detailed description of your changes." + $ git push origin name-of-your-bugfix-or-feature + +9. Submit a pull request through the GitHub website. + +Pull Request Guidelines +----------------------- + +When you submit a pull request, check that it meets these guidelines: + +1. Try to keep pull requests small. +2. Make frequent but logical commits, and follow the commit-message guildlines below. +3. Fix any formatting/linting issues that pre-commit finds. (pre-commit should prevent you from commiting if you don't) +4. All algorithms need documentation! Don't forget the .rst files in the /docs directory. +5. Most pull request should include tests. +6. Check the GitHub Actions status and make sure that the tests pass for all supported Python versions and platforms. +7. Don't take requests to change your code personally! + +Commit Message Guidelines +------------------------- Commit messages should be clear and follow a few basic rules. Example: @@ -60,18 +145,4 @@ Standard acronyms to start the commit message with are: |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 +|WIP | Commit that is a work in progress | \ No newline at end of file