From 57a578246306ed08a6f9632c7eec76abf9e7c5fb Mon Sep 17 00:00:00 2001 From: Christine Dodrill Date: Sat, 14 Feb 2015 09:10:28 -0800 Subject: [PATCH] Add some older blogposts --- blog/pursuit-of-dsl-2014-08-16.markdown | 111 ++++++++++++++++++ .../thoughts-on-community-2014-07-31.markdown | 94 +++++++++++++++ 2 files changed, 205 insertions(+) create mode 100644 blog/pursuit-of-dsl-2014-08-16.markdown create mode 100644 blog/thoughts-on-community-2014-07-31.markdown diff --git a/blog/pursuit-of-dsl-2014-08-16.markdown b/blog/pursuit-of-dsl-2014-08-16.markdown new file mode 100644 index 0000000..e812b04 --- /dev/null +++ b/blog/pursuit-of-dsl-2014-08-16.markdown @@ -0,0 +1,111 @@ +Pursuit of a DSL +================ + +A project we have been working on is [Tetra](http://github.com/Xe/Tetra). It is +an extended services package in Go with Lua and Moonscript extensions. While +writing Tetra, I have found out how to create a Domain Specific Language, and +I would like to recommend Moonscript as a toolkit for creating DSL's. + +[Moonscript](http://moonscript.org) is a high level wrapper around Lua designed +to make programming easier. We have used Moonscript heavily in Tetra because of +how easy it is to make very idiomatic code in it. + +Here is some example code from the Tetra codebase for making a command: + +```moonscript +require "lib/elfs" + +Command "NAMEGEN", -> + "> #{elfs.GenName!\upper!}" +``` + +That's it. That creates a command named `NAMEGEN` that uses `lib/elfs` to +generate goofy heroku-like application names based on names from [Pokemon Vietnamese Crystal](http://tvtropes.org/pmwiki/pmwiki.php/JustForFun/PokemonVietnameseCrystal). + +In fact, because this is so simple and elegant, you can document code like this +inline. + +## Command Tutorial + +In this file we describe an example command `TEST`. `TEST` will return some +information about the place the command is used as well as explain the +arguments involved. + +Because Tetra is a polyglot of Lua, Moonscript and Go, the relevant Go objects +will have their type definitions linked to on [godoc](http://godoc.org) + +Declaring commands is done with the `Command` macro. It takes in two arguments. + +1. The command verb +2. The command function + +It also can take in 3 arguments if the command needs to be restricted to IRCops +only. + +1. The command verb +2. `true` +3. The command function + +The command function can have up to 3 arguments set when it is called. These +are: + +1. The [Client](https://godoc.org/github.com/Xe/Tetra/bot#Client) that + originated the command call. +2. The [Destination](https://godoc.org/github.com/Xe/Tetra/bot#Targeter) or + where the command was sent to. This will be a Client if the target is an + internal client or + a [Channel](https://godoc.org/github.com/Xe/Tetra/bot#Channel) if the target + is a channel. +3. The command arguments as a string array. + +```moonscript +Command "TEST", (source, destination, args) -> +``` + +All scripts have `client` pointing to the pseudoclient that the script is +spawned in. If the script name is `chatbot/8ball`, the value of `client` will +point to the `chatbot` pseudoclient. + +```moonscript + client.Notice source, "Hello there!" +``` + +This will send a `NOTICE` to the source of the command saying "Hello there!". + +```moonscript + client.Notice source, "You are #{source.Nick} sending this to #{destination.Target!} with #{#args} arguments" +``` + +All command must return a string with a message to the user. This is a good +place to do things like summarize the output of the command or if it worked or +not. If the command is oper-only, this will be the message logged to the +services snoop channel. + +```moonscript + "End of TEST output" +``` + +See? That easy. + +```moonscript +Command "TEST", -> + "Hello!" +``` + +This is much better than Cod's + +```python +#All modules have a name and description +NAME="Test module" +DESC="Small example to help you get started" + +def initModule(cod): + cod.addBotCommand("TEST", testbotCommand) + +def destroyModule(cod): + cod.delBotCommand("TEST") + +def testbotCommand(cod, line, splitline, source, destination): + "A simple test command" + return "Hello!" +``` diff --git a/blog/thoughts-on-community-2014-07-31.markdown b/blog/thoughts-on-community-2014-07-31.markdown new file mode 100644 index 0000000..ecf8b73 --- /dev/null +++ b/blog/thoughts-on-community-2014-07-31.markdown @@ -0,0 +1,94 @@ +Thoughts on Community Management +================================ + +Many open source community projects lack proper management. They can put too +much of their resources in too few places. When that one person falls out of +contact or goes rogue on everyone, it can have huge effects on everyone +involved in the project. Users, Contributors and Admins. + +Here, I propose an alternative management structure based on what works. + +## Organization + +Contributors and Project Administrators are there to take input/feedback from +Users, rectify the situation or explain why doing so is counterproductive. +Doing so will be done kindly and will be ran through at least another person +before it is posted publicly. This includes (but is not limited to) email, IRC, +forums, anything. A person involved in the project is a representative of it. +They are the face of it. If they are rude it taints the image of everyone +involved. + +## Access + +Project Administrators will have full, unfiltered access to anything the +project has. This includes root access, billing access, everything. There will +be no reason to hide things. Operational conversations will be shared. All +group decisions will be voted on with a simple Yes/No/Abstain process. As such +this team should be kept small. + +## Contributions + +Contributors will have to make pull requests, as will Administrators. There +will be review on all changes made. No commits will be pushed to master by +themselves unless there is approval. This will allow for the proper review and +testing procedures to be done to all code contributed. + +Additionally, for ease of scripts scraping the commits when something is +released, a commit style should be enforced. + +### Commit Style + +The following section is borrowed from [Deis' commit +guidelines](https://github.com/deis/deis/blob/master/CONTRIBUTING.md). + +--- + +We follow a rough convention for commit messages borrowed from CoreOS, who borrowed theirs +from AngularJS. This is an example of a commit: + + feat(scripts/test-cluster): add a cluster test command + + this uses tmux to setup a test cluster that you can easily kill and + start for debugging. + +To make it more formal, it looks something like this: + + + {type}({scope}): {subject} + + {body} + + {footer} + +The {scope} can be anything specifying place of the commit change. + +The {subject} needs to use imperative, present tense: “change”, not “changed” +nor “changes”. The first letter should not be capitalized, and there is no dot +(.) at the end. + +Just like the {subject}, the message {body} needs to be in the present tense, +and includes the motivation for the change, as well as a contrast with the +previous behavior. The first letter in a paragraph must be capitalized. + +All breaking changes need to be mentioned in the {footer} with the description +of the change, the justification behind the change and any migration notes +required. + +Any line of the commit message cannot be longer than 72 characters, with the +subject line limited to 50 characters. This allows the message to be easier to +read on github as well as in various git tools. + +The allowed {types} are as follows: + + feat -> feature + fix -> bug fix + docs -> documentation + style -> formatting + ref -> refactoring code + test -> adding missing tests + chore -> maintenance + +--- + +I believe that these guidelines would lead towards a harmonious community. +