Add some older blogposts
This commit is contained in:
Christine Dodrill
parent
285a626e76
commit
57a5782463
|
|
@ -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!"
|
||||||
|
```
|
||||||
|
|
@ -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}
|
||||||
|
<BLANK LINE>
|
||||||
|
{body}
|
||||||
|
<BLANK LINE>
|
||||||
|
{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.
|
||||||
|
|
||||||
Loading…
Reference in New Issue