From ef5c8333c5bcdec9eb0512ffe7f9419240af0f36 Mon Sep 17 00:00:00 2001 From: errbufferoverfl Date: Fri, 24 Mar 2017 11:44:42 +1100 Subject: [PATCH] Updated documentation and added contributing guide --- CONTRIBUTING.md | 45 +++++++++++++++++++++++++++++++++++++++++++++ README.md | 36 +++++++++++++++++------------------- 2 files changed, 62 insertions(+), 19 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..fb454c7 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,45 @@ +# Contributing + +First off, thank you for considering contributing to USB Canary. + +### 1. Where do I go from here? + +If you've noticed a bug or have a question [search the issue tracker](https://github.com/probablynotablog/usb-canary/issues?q=something) +to see if someone else in the community has already created a ticket. If not, go ahead and [make one](https://github.com/probablynotablog/usb-canary/issues/new)! + +### 2. Fork & create a branch + +If this is something you think you can fix, then [fork USB Canary](https://help.github.com/articles/fork-a-repo) +and create a branch with a descriptive name. + +A good branch name would be (where issue #325 is the ticket you're working on): + +```sh +git checkout -b 325-add-windows-support +``` + +#### 3. Did you find a bug? + +* **Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/probablynotablog/usb-canary/issues). + +* If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/probablynotablog/usb-canary/issues/new). +Be sure to include a **title and clear description**, as much relevant information as possible - use the relevant bug report templates to create the issue. + +### 5. Implement your fix or feature + +At this point, you're ready to make your changes! Feel free to ask for help; everyone is a beginner at first. + +### 6. Test your changes + +We don't currently have an automated test suite, so it's up to you to test your bug fix or feature to ensure it does not impact exsisting features, unless that feature was really a bug and you're fixing it. If you're unable to test your new feature, reach out to one of the maintainers who will be happy to help. (It may take longer to be accepted) + +### 7. Make a Pull Request + +At this point, you should switch back to your master branch and make sure it's +up to date with USB Canary's master branch. + +Push it! + +Finally, go to GitHub and [make a Pull Request](https://help.github.com/articles/creating-a-pull-request). + + diff --git a/README.md b/README.md index 89a6076..3759621 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ There are a couple of 3rd party libraries to get USB canary running - for some t - [slackclient](https://github.com/slackapi/python-slackclient) - A basic client for Slack.com, which can optionally connect to the Slack Real Time Messaging (RTM) API. - [twilio](https://github.com/twilio/twilio-python) - A Python module for communicating with the Twilio API and generating TwiML - [pyudev](https://github.com/pyudev/pyudev) - Python bindings to libudev (with support for PyQt4, PySide, pygobject and wx) +- [sander-daemon](https://github.com/serverdensity/python-daemon) - Jejik daemon class improved by Server Density These can all be installed via `pip`, in some cases you may need to use `pip` with `sudo`. You can install the packages as follows: @@ -17,6 +18,7 @@ These can all be installed via `pip`, in some cases you may need to use `pip` wi pip install slackclient pip install twilio pip install pyudev +pip install sander-daemon ``` Otherwise you can just run `pip install -r requirements.txt` @@ -61,23 +63,23 @@ An example `settings.json` file: Note that `paranoid`, `slack`, and `twilio` are boolean values and should be set to `true` or `false`. If the file is formatted incorrectly and it cannot be parsed, you will get a `ValueError`, you can use [JSONLint](http://jsonlint.com/) if you find yourself having issues with this. - USB Canary, is sort of smart and can 'detect' if you are running `XScreenSaver` or `gnome-screensaver` on your - computer, this is done by just checking which packages are installed via the `apt` library, if both of them are - installed though, it will leave you to determine which one you are using - if you have an unsupported - screensaver, don't fret, you can still run it in paranoid mode. +USB Canary, is sort of smart and can 'detect' if you are running `XScreenSaver` or `gnome-screensaver` on your +computer, this is done by just checking which packages are installed via the `apt` library, if both of them are +installed though, it will leave you to determine which one you are using - if you have an unsupported +screensaver, don't fret, you can still run it in paranoid mode. - Paranoid mode is also suitable for people who want to monitor if their servers have had USB's plugged into them, - although I haven't tested them on Linode, Amazon Web Services, or Digital Ocean it is suitable for those with - physical servers that may need this sort of monitoring. +Paranoid mode is also suitable for people who want to monitor if their servers have had USB's plugged into them, +although I haven't tested them on Linode, Amazon Web Services, or Digital Ocean it is suitable for those with +physical servers that may need this sort of monitoring. - To start the application: - ```shell +To start the application: +```shell ./usb_canary.py start | stop | restart ``` ## Deployment The following will outline the basic steps to deploying USB Canary to Slack and Twilio. As extra services are -supported, please ensure you add appropriate documentation. +added, please ensure you add appropriate documentation with your PR. ### Twilio To use the Twilio intergration you will need to get an: @@ -107,9 +109,6 @@ usb-canary ├──LICENSE.txt ├──settings.json ├──canary -│ ├──daemon -│ │ ├──__init__.py -│ │ └──daemon.py │ ├──slack │ │ ├──slack.py │ │ ├──slack_bot.py @@ -128,6 +127,8 @@ usb-canary │ └──__init__.py ├──README.md <---------------------------------- YOU ARE HERE ├──requirements.txt +├──ISSUE_TEMPLATE.md +├──PULL_REQUEST_TEMPLATE.md └──usb_canary.py ``` Under the main `canary` directory you will find folders for different services such as Twilio which is named `twilleo` @@ -141,14 +142,11 @@ Screensaver having their own file, just to keep things tidy. - [slackclient](https://github.com/slackapi/python-slackclient) - A basic client for Slack.com, which can optionally connect to the Slack Real Time Messaging (RTM) API. - [twilio](https://github.com/twilio/twilio-python) - A Python module for communicating with the Twilio API and generating TwiML - [python-apt](https://apt.alioth.debian.org/python-apt-doc/library/index.html) - A library that provides access to almost every functionality supported by the underlying apt-pkg and apt-inst libraries +- [sander-daemon](https://github.com/serverdensity/python-daemon) - Jejik daemon class improved by Server Density ## Contributing -1. Fork it! -2. Create your feature branch: `git checkout -b my-new-feature` -3. Commit your changes: `git commit -am 'Add some feature'` -4. Push to the branch: `git push origin my-new-feature` -5. Submit a pull request +See the [CONTRIBUTING.md](CONTRIBUTING.md) file for details. ## Versioning @@ -167,4 +165,4 @@ This project is licensed under the GNU GPLv3 License - see the [LICENSE.txt](LIC ## Acknowledgements -- Sander Marechal - I don't know who you are, but you made damonizing this so much easier! +- [timball](https://github.com/timball) - for recommending `sander-daemon`