diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a621405..2ed1bf9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,7 +10,7 @@ 3. Make the change, * Follow code conventions, * Test your code to make sure it works right, -4. Make a pull request (bonus points for topic branches), +4. Make a pull request, 5. Make any requested adjustments, 6. If/When accepted, party :tada: @@ -18,92 +18,120 @@ You will need the following tools to contribute to JBot: -* [RVM](https://rvm.io/) -* Ruby -* Bundler -* Git -* SQLite3 -* MySQL + * [RVM with Ruby 1.9.2 or Greater](https://rvm.io/) + * [Bundler](http://gembundler.com/) + * Git + * SQLite3 + * MySQL If you are not familiar with Git, check out the [free ebook](http://git-scm.com/book/). ## Working on JBot Working on JBot requires a working knowledge of Ruby, as that is the language -it is written in. +it is written in. YAML and JSON are also handy to know. + +JBot is built on the [Cinch framework](https://github.com/cinchrb/cinch). Check +out the [docs for Cinch](http://www.rubydoc.info/github/cinchrb/cinch/master) to +learn how to use it. ### Setup -These commands will get you setup to run Showbot. +To get JBot up and running for development, follow the +[setup steps in README.md](https://github.com/rikai/Showbot/blob/devel/README.md#setup) +for running the development version of JBot. All development for JBot takes +place on the `devel` branch, so make sure you're on it! + +### Quick Start + +The quickest way to get started with JBot is to build a plugin. We have written +[QUICKSTART.md](https://github.com/rikai/Showbot/blob/devel/docs/dev/QUICKSTART.md) +in docs/ detailing how to quickly create a simple plugin for JBot. + +### Important files + +There are a few files that are most important when developing for JBot. Below is +and outline of what those files are and how they work. - * `git clone https://github.com/rikai/Showbot.git` - * `cd Showbot` - * `git checkout devel` - * `bundle` - * `foreman run rake db:migrate` +#### cinchize.yml -Finally you need to setup your `.env` file in the root of the project. At the -bare minimum you'll need the following: +The `cinchize.yml` file is the core configuration file for JBot. In it, various +settings can be set for both the core and the plugins. Plugins can also be +activated/deactivated based on whether they are specified in the file. This +means that a plugin can be turned off by simply commenting out it's name and +config data in `cinchize.yml`. -``` -# Bot lib folder -RUBYLIB=./lib +A `cinchize.yml.example` file has been added to the repo to show an example +configuration, as well as to show all the available options and plugins. As +plugins are added, example configurations are added to the example file. Some +plugins require a number of different configuration options while others require +no options at all. The easiest way to build your `cinchize.yml` file is to copy +the example file and edit it according to your particular needs. -# Set this if you want to use a language other than english. -# You will also need to create a corresponding .yml file in the locales folder. -SHOWBOT_LOCALE=en +The `cinchize.yml` file is written in [YAML](http://en.wikipedia.org/wiki/YAML). -# Foreman stuff -## Production port -PORT=80 -## Development port -DEVELOPMENT_PORT=5000 +#### data.json -# Point this to the url of data.json, if you have one -SHOWBOT_DATABASE_URL=your_info_here +This file is used by several JBot plugins. The `data.json` file contains +information about whether there is a live show, and when it is. There is no +example version of this file in the repository. Currently, this file is +generated externally, and lives in `public/`. To use it (and for the plugins +that depend on it to work correctly), you must start JBot's web server. +Alternately, you can point JBot at an externally hosted data.json file by +setting the configuration in your `.env` file. -# For backup.rb -BOT_DATABASE_NAME=your_info_here -BOT_DATABASE_USER=your_info_here -BOT_DATABASE_PASSWORD=your_info_here -BOT_DATABASE_HOST=your_info_here -BOT_DATABASE_PORT=your_info_here -BOT_DATABASE_OPTS=your_info_here -S3_ACCESS_KEY_ID=your_info_here -S3_SECRET_ACCESS_KEY=your_info_here -S3_REIGON=your_info_here -S3_BUCKET=your_info_here -S3_PATH=your_info_here -S3_KEEP=your_info_here +The `data.json` file has separate [additional documentation](https://github.com/rikai/Showbot/blob/master/docs/dev/DATA.JSON.md). -# Point this to the url of data.json, if you have one -DATA_JSON_URL=your_info_here -``` +#### public/shows.json -### Configuring IRC +This file is closely related to the `data.json` file, and is also used +independently by several plugins. It provides a list of shows (and some data +about them) to JBot. - * Customize [`cinchize.yml`](https://github.com/rikai/Showbot/blob/master/cinchize.yml) for your IRC channel. - * Update [`fix_name`](https://github.com/rikai/Showbot/blob/master/lib/cinch/plugins/showbot_admin.rb#L54) to match your bot's name. + -### Launching Showbot +#### .env -**Website and the IRC Bot** +The `.env` file sets environment variables for JBot. The `.env.example` file is +included in the repo for exemplary purposes. The most important field that needs +set in this file is `DATA_JSON_URL`. You should point that at a URL for your +`data.json` file. -``` -$ bundle exec foreman start -f Procfile.local -``` +#### showbot_irc.rb and showbot_web.rb -**Just the Website** +The `showbot_irc.rb` and `showbot_web.rb` files are the bootstrappers for JBot. +They start up the IRC and web components of JBot. You **should not** need to +change `showbot_irc.rb`. If you find yourself needing to change something in +there, [open an issue](https://github.com/rikai/Showbot/issues/new) and talk to +us about it first. Otherwise, your contributions may not be accepted. -``` -$ bundle exec foreman start web -f Procfile.local -``` +The `showbot_web.rb` file, on the other hand, contains much of the logic for the +web interface for JBot. This means that sometimes it can change. Inside of this +file, you will find that JBot's web interface is a Sinatra web application that +shares a database with the IRC bot. -**Just the IRC Bot** +#### lib/cinch/plugins/* -``` -$ bundle exec foreman start irc -f Procfile.local -``` +This directory holds all of JBot's plugins, which define JBot's core functions, +a.k.a. all the things that make JBot such a nice bot. Most development happens +in these files, and in the related `lib/models/` directory. If you are adding +something new to JBot, this is the most likely starting point. + +Plugin classes must all be in the `Cinch::Plugins` module, and must include the +`Cinch::Plugin` module to work correctly. New plugins must also be added to the +`cinchize.yml` file to be loaded by JBot. + +#### lib/models/* + +The `lib/models/` directory contains all of the model classes used by JBot's +plugins. All models are `require`d at application start, and so are always +available to plugins. You _may_ use models from another plugin if it suits your +needs, **but** please don't mess with a model's internal global state (as +another plugin may depend on that), and please don't instantiate new instances +of models that use up resources (such as hitting an API endpoint, as those are +often limited). If you need to use such a model across multiple plugins, please +[open an issue](https://github.com/rikai/Showbot/issues/new) and talk to us +about it first. ## Code conventions @@ -116,4 +144,3 @@ $ bundle exec foreman start irc -f Procfile.local * Functions/Methods: `def snake_case` * Variables, parameters, etc: `snake_case = 42` * Spaces around operators -