Making Will Better and Better
Will is built entirely on the shoulders of giants, and has a great community of developers that move it forward. He wouldn't exist without all of them.
We also welcome new contributions no matter how big or small. Interested in contributing to will? We'd love to have you. Details below.
Anyone is welcome to contribute to will, regardless of skill level or experience. To make will the best he can be, we have one big, overriding cultural principle:
Simple. Easy, right?
We've all been newbie coders, we've all had bad days, we've all been frustrated with libraries, we've all spoken a language we learned later in life. In discussions with other coders, PRs, and CRs, we just give each the benefit of the doubt, listen well, and assume best intentions. It's worked out fantastically.
This doesn't mean we don't have honest, spirited discussions about the direction to move will forward, or how to implement a feature. We do. We just respect one other while we do it. Not so bad, right? :)
Improve will's core
For big core features, you're probably best off opening an issue, and discussing it with one of the core developers before you hack your nights and weekends away.
Core changes to will are very much welcome. In some cases, proposed changes have already been thought through, and there may be gotchas or sticking points we couldn't get past. In other cases, it might be a direction we've purposely decided not to take will. In most cases, we simply haven't thought of it, and would love the improvement!
It's always great to get a heads up of what's coming down the pipe, and have an open dialog. Thanks for reaching out and starting one!
In terms of the mechanics, you'll just want to:
- Fork this repo.
- Clone down a copy, set up redis and the env, as before.
./start_dev_will.pyto start up just core will.
Contribute new plugins
This one's pretty simple. Write good, clean code that does one thing well, document it properly, and submit a PR!
To submit a plugin that's running in your will,
- Fork this repo.
- Clone down a copy, set up redis and the env, as before.
pip install -r requirements.dev.txt
- Copy your plugin and docs over to the core will repo,
./start_dev_will.pyto start up just core will, and test it out!
Code standards and PRs
This one's hopefully straightforward:
- Incoming code should follow PEP8
- If you add new core-level features, please add documentation in the
docsfolder (we use mkdocs). If you're not sure if they're needed, just ask!
- Please add your name and attribution to the AUTHORS file.
- Know you have our thanks for helping to make will even better!
Shamefully, tests are just getting rolling, and a proper, well-architected test harness is in the works. However, there are some tests you can run by running:
coverage run -m nose
The Shoulders of Giants
Will leverages some fantastic libraries. He wouldn't exist without them.
- Bottle for http handling,
- Jinja for templating,
- Sleekxmpp for listening to xmpp,
- natural and parsedatetime for natural date parsing,
- apscheduler for scheduled task parsing,
- Requests to make http sane.
Will's also has had help from lots of coders. Alphabetically:
- adamcin gave you html support in 1-1 chats, using the new v2 API, and made bootstrapping more reliable.
- adamgilman gave you the friendly error messages when the hipchat key was invalid.
- amckinley fixed a bug in the hipchat user list from missing params.
- bfhenderson removed dependence on the v1 token, and made help more friendly.
- borgstrom gave you beautifully architected storage backends, including support for couchbase and local storage.
- brandonsturgeon jumped on hipchat's API-breaking change, and made will immune in a flash. Improved the docs all over, too.
- BrianGallew improved the blacklist import mechanism, so blacklisted modules aren't even attempted to be imported, taught will to handle zombie users with grace, and fixed the file storage backend.
- bsvetchine fixed a bug with README generation.
- buran added HTML support to 1-1 messages.
- carsongee pooled your redis connections.
- camilonova fixed the
@randomlydecorator, and brought the joy of more pugs to your life. He's also reported several important bugs.
- ckcollab was one of the original contributors, when will was first built at GreenKahuna.
- charlax gave us batch-get of rooms via the V2 API.
- chillipeper fixed up the max-size and handling of V2 rooms.
- crccheck gave you friendly error messages if your
- d0ugal fixed up the docs to meet the new mkdocs standard.
- danbourke submitted a fix for the >2000 rooms bug, and kept Will happy.
- derek-adair found a solution for the duplicated 'hi' messages.
- dpoirier figured out how to properly ignore the initial catch-up messages, and gave you log-level control.
- dmuntean gave you proxy support, and kept it working..
- Ironykins brought you urban dictionary support.
- kenden fixed up the redis docs for ubuntu/debian.
- jbeluch found a bug with
get_rosternot populating in time.
- jcdyer made the
_available_roomsobject consistent across API versions.
- jessamynsmith was kind enough to port talkbackbot over, at my request, then kept it updated through version changes.
- jquast did the noble and oft unappreciated work of spelling fixes.
- keNzi added shorten url function using bitly service.
- levithomason was one of the original contributors, when will was first built at GreenKahuna.
- mark-adams cleaned up a Bitbucket typo.
- hobson made setup.py more robust across operating systems, and improved the docs.
- neronmoon made it easier to mention will with non-standard case
- michaeljoseph suggested improvements to setup and requirements.txt format.
- mrgrue added support for the hipchat server beta.
- mvanbaak brought you support for bitbucket uptime.
- netjunkie fixed a duplicated help module, added an expire parameter to
self.save(), and added support for will watching hipchat's status.
- pcurry added travis support.
- pepedocs added friendly timestamps to the default logging output.
- PrideRage gave you access to a room's entire history, and suggested a better talkback regex.
- quixeybrian wrote the awesome new help system and stopped the rate limit nightmare.
- Regner upgraded the hiredis version to work on windows.
- rbp added the
admin_onlyargument, and fixed a bug with
roomnot being passed along properly to messages.
- shadow7412 cleaned up a bunch of regex, and fixed up
image meafter google pulled the free API.
- sivy added a config flag for disabling SSL, and the ability to look up a user by nickname.
- tomokas fixed a bug in the
- tophsic made help friendlier, including plugin-specific help.
- wohali tracked down the annoying DNS thread issue, and got will on the right path.
- woohgit added support for the v2 WorldWeatherOnline API, and fixed it when I broke it, and then fixed it again when they changed their endpoint. He also taught will how to say his version number. And
remind ___ to ___ at ___. Awesome. And fixed lots of docs. And put the time zone with "what time is it?". And then added an entire Pagerduty workflow. And made message parsing more reliable. And wrote the ACL support. And even more doc fixes. And improvements on uptime monitoring edge cases. And kept Pagerduty working. And added
poplist support. Yep.
- woparry made sure that Will could handle organizations with a massive (>2000) number of rooms.
If you're looking for plugin inspiration, here are some wills that are open-sourced:
Note: Have a will you've open-sourced? Please send it in a PR or Issue! This list is tiny!
0.9.4 - April 25, 2017 (scheduled, please test on master and report!)
New releases and movement again! Exciting things in the pipeline for will, and that's starting with a long-awaited release. Thanks to everyone who both submitted code, and had saint-like patience with it being merged in.
self.pop()methods to support list storage, thanks to woohgit.
@will image meworks again (but requires a google API key - see
config.py, thanks to shadow7412.
@will pugsthankfully works again, thanks to gordol.
@will help <plugin>now gives plugin-specific help, thanks to tophsic.
- Improvement: Blacklisted modules aren't even attempted to be imported, thanks to BrianGallew.
- Improvement: File storage engine expires properly, thanks to BrianGallew.
- Improvement: Zombie users no longer cause will trouble, thanks to BrianGallew.
- Improvement: Will now no longer gets stuck if organizations have more than 2000(!) hipchat rooms, courtesy of woparry and danbourke.
- Improvement: V2 API calls for multiple rooms now properly uses
max-resultsand doesn't hang, thanks to chillipeper.
- Improvement: Much-improved test runners, and proper case for Bitbucket, thanks to mark-adams.
_available_roomsis now populated with
Roomobjects, regardless of whether you use V1 or V2, thanks to jcdyer.
- Improvement: Output logging now includes timestamps by default, thanks to pepedocs.
- Improvement: Upgraded to
hiredis> 0.2 to get windows builds working, thanks to Regner.
- Improvement: Updated to the new pagerduty docs, thanks to woohgit.
- Improvement: Generation script doesn't make a duplicate
hiresponse, thanks to brandonsturgeon and derek-adair.
0.9.3 - September 11, 2015
Thanks for your patience on this long-delayed release! Here's what's new:
- New: Will watches bitbucket, and alerts on downtime, thanks to mvanbaak.
@will urban dictionary ______, thanks to Ironykins.
- New: 1-1 messages now support HTML, thanks to AndrewBurdyug and brandonsturgeon
- Improvement: Batch-getting of rooms, thanks to charlax.
- Improvement: Better handling of uptime check edge cases, thanks to woohgit.
- Improvement: Proper docs for installing redis on ubuntu/debian, thanks to kenden.
- Improvement: Pulled an extraneous doc page, thanks to woohgit.
- Improvement: Fixes to the route doc syntax, thanks to brandonsturgeon.
- Improvement: Docs now fit the new mkdocs format, thanks to d0ugal.
- Improvement: New travis.yml setup for easier travis running, and plugged my CircleCI builds into the github repo. All future PRs should automatically have tests run!
0.9.2 - June 5, 2015
- Fixes bug that caused will not to join all rooms if
ROOMSwas missing. Thanks to camilonova for the report!
0.9.1 - May 30, 2015
- Fixes bug that affected
@wills - thanks to woohgit for the report!
0.9 - May 29, 2015
- BREAKING: Module change. New
will.plugins.funmodule. Existing will installs will need to add it to your
config.pyto keep the fun!
- New: Support for Pagerduty workflows, thanks to woohgit. This is really tremendous stuff. Check out the docs here!
- New: Pluggable storage backends, with support for couchbase and local file storage, in addition to redis. Many thanks to borgstrom
- New: ACL functionality, thanks to woohgit. Backwards-compatable, even!
- New: Made will a little more fun, thanks to camilonova. Hint: it involves the world's most meme-friendly dog.
- New: Will can now construct google poems, thanks to AirbornePorcine. Truly, his creativity knows no bounds.
- Improvement: Moved stuff like that into a new "fun" module. Dry, anti-fun people can now disable it more easily. ;)
- Improvement: "What time is it" now outputs time zones, thanks to woohgit.
- Improvement: No more rate-limit problems on the v2 token, thanks to grundprinzip.
- Improvement: Messages are now
.strip()ed before being compared, to handle frozen-fingered-typos. Thanks, woohgit!
- Fix: Typo in the docs gone. Thanks, woohgit.
- Fix: Bugs in proxy support are fixed, thanks to dmuntean.
0.8.2 - April 24, 2015
- Fixes an odd remaining bug with
@randomly, thanks to camilonova's continued debugging.
0.8.1 - April 23, 2015
versionplugin into admin, so it just works for most users.
0.8 - April 23, 2015
- What happens when life gets busy and we go a full month and a half between will releases? Lots and lots:
- New: All-new
@will who is in this room?command, thanks to puug.
- New: Will now can shorten links via bitly
@will bitly http://example.com, thanks to keNzi.
- New: Will now supports a
PROXY_URLsetting, for getting around funky firewalls, thanks to dmuntean.
@will versioncommand to check version number, thanks to woohgit.
- New: Awesome new
remind ___ to ___ at ___, thanks to woohgit.
- New: Will now keeps an eye on hipchat's uptime as well, thanks to netjunki.
- Fix: a breaking bug in the
@randomlydecorator, thanks to a report by camilonova.
- Support: Handles a breaking change in the hipchat API, thanks to brandonsturgeon.
- Support: Updates to v2 of the underquoted API, thanks jessamynsmith.
- Support: Updated to the new WorldWeatherOnline endpoint, since they had DDOS problems, thanks to woohgit.
- Improvement: The most important kind of PRs. Spelling fixes. Many thanks to jquast.
self.save()now accepts an
expirevalue, thanks to netjunki.
- Improvement: PEP8 passes for the whole codebase, with flake8 added to automated tests.
0.7.3 - March 3, 2015
- Fixed a breaking bug to world time, thanks to woohgit.
0.7.2 - February 27, 2015
- Improved handling when
.reply()is called incorrectly, thanks to a report by dothak
- Fixed the annoying "github's ok" on first launch.
- Restored Python 2.6 compatability thanks to the report and patience of JPerkster.
- Lots of code cleanup toward pep8.
0.7.1 - February 5, 2015
- Improved talkbackbot regex, suggested by PrideRage.
0.7.0 - February 4, 2015
- Adds a port of the awesome talkbackbot, thanks to jessamynsmith, who super-kindly ported it at my request!
- Oh, yeah. That port also includes the first proper tests in will, and a pretty solid pattern for testing plugins. Woo! More huge thanks to jessamynsmith.
0.6.9 - January 30, 2015
- Fixed copypasta error caught by the keen eye of dpoirier.
0.6.8 - January 30, 2015
- Will now supports templates directories within plugins. Just put a
templatesdirectory in the plugin's module, and it will be detected. Thanks to sivy for the idea and willingness to get it done!
0.6.7 - January 29, 2015
- Addition of
.get_user_by_nick()method, to look up users by nick, thanks to sivy.
- Bugfix to
ALLOW_INSECURE_HIPCHAT_SERVERwhen specified in
config.py, thanks to sivy.
0.6.6 - January 29, 2015
room.historyattribute with a room's history, thanks to PrideRage
- New setting:
ALLOW_INSECURE_HIPCHAT_SERVER, which will disable SSL checks (you're on your own), thanks to sivy.
- Adds support for V2 of the WorldWeatherOnline API (used for world times, weather) thanks to woohgit.
- Adds new release and doc deploy scripts, so the github releases are kept up to date. Thanks to crccheck for noticing and reporting they were stale!
0.6.5 - January 23, 2015
- Removes mkdocs from the production requirements.txt to fix a Jinja version problem. Thanks to the report from PrideRage.
0.6.4 - January 19, 2015
- Switches to bottle to cherrypy over gevent, which should solve lingering gevent DNS threading issues, thanks to wohali.
- Support for @will, @WILL, @wIll, thanks to neronmoon
0.6.3 - December 30, 2014
- Better error handling for weirdly formatted messages.
- Better generated README, thanks to bsvetchine.
0.6.2 - September 23, 2014
- Bugfix on
generate_will_project, thanks to the report by MattyDub.
0.6.1 - September 23, 2014
- Freezes apscheduler to < 3.0, since its API was backwards incompatibile.
0.6.0 - September 17, 2014
- Methods in a single class now share a common instance, thanks to amckinley.
- Redis connections are now pooled (which should help with "max clients exceeded" errors), thanks to carsongee.
- Preliminary travis ci support, thanks to pcurry.
- More gramatically correct documentation by hobson.
0.5.7 - September 3, 2014
- Improvements to setup.py to be robust a variety of linux/unixes by hobson.
0.5.6 - August 26, 2014
- Fix for 1-1 bootstrapping bug, thanks to adamcin.
0.5.5 - August 25, 2014
- Full html support in 1-1 chats, thanks to adamcin.
0.5.4 - July 22, 2014
- Upgrades bottle to 0.12.6 to fix security bug.
0.5.3 - July 11, 2014
@randomlyfunctions now can run on the 59th minute, thanks to tomokas.
- Bad merge that duplicated
help.pyfixed by netjunki.
- "global name 'params' is not defined" bug fixed by amckinley.
0.5.1 - July 2, 2014
0.5 Omnibus - June 27, 2014
- Big, big release, with backwards-incompatble changes. Please read all the notes on this one!
- All-new config and environment setup, including an all-new
config.pyfor plugin configuration, and all non-sensitive settings.
- Much, much improved bootstrapping code that validates settings, gives helpful output, and generally helps you get will running.
- Documentation! Real-live documentation!
WILL_TOKENhas been renamed
@require_settingsdecorator for plugins to request validation that needed settings are present.
- Will now has a concept of modules (groups of plugins), and groups help output according.
0.4.10 - June 6, 2014
respond_to(), thanks to rbp. If a user is not in
WILL_ADMINS, they won't be able to run any
admin_only=Trueplugins. Default for
WILL_ADMINSis all users to retain backwards-compatibility.
- All commands in the
storage.pyplugin are now admin-only.
helpnow only responds to direct asks, allowing other plugins to handle "help me with x", thanks to bfhenderson
0.4.9 - May 28, 2014
- Passing a
.say()now works properly, thanks to rbp.
- New optional
WILL_LOGLEVELsetting, thanks to dpoirier.
0.4.8 - May 21, 2014
- Will now ignores all previously sent messages properly, by passing in
botas the resource instead of an ugly time hack, thanks to dpoirier.
0.4.7 - May 15, 2014
- Will now prints a helpful message if one of your
WILL_ROOMSis wrong, and continues starting, instead of crashing in a fiery ball, thanks to crccheck.
0.4.6 - May 5, 2014
@routedecorators now honor all bottle arguments, most helpfully
0.4.5 - May 2, 2014
- Awesome new help system by quixeybrian.
- "@will help" now only displays functions with docstrings, and formats them nicely.
- Old help (regexes and all) is available at "@will programmer help"
0.4.4 - April 22, 2014
- Removes the dependence on the v1 token (though it still helps with rate-limiting), thanks to bfhenderson.
- Much friendlier error message on an invalid API key, thanks to adamgilman.
0.4.3 - ~ April 1, 2014
- Support for hundreds of users and rooms without hitting the API limit.
get_all_usersuse of the bulk API added by quixeybrian. Thanks also to jbeluch and jdrukman for nudges in the right direction.
- The start of some useful comments - the meat of will was hacked out by one person over a handful of days and it looks that way. Slowly but surely making this codebase more friendly to other contributions!
- Added a CONTRIBUTING.md file thanks to michaeljoseph.
- Proper releases in the docs, and an updated
AUTHORSfile. If you see something awry, send a PR!
0.4 - ~ March 2014
Ye olden past before we started keeping this list. All contributions by GreenKahuna. Will did everything that's not in the release list above. That's called lazy retconning release lists!
Make sure nothing from the readme is missed.