Skip to content

Commit

Permalink
Merge pull request #38 from jgonggrijp/update-docs
Browse files Browse the repository at this point in the history 
Conflicts:
	Authors.txt
	Dependencies.md

Also added line breaks to Platforms.md.
  • Loading branch information
@jgonggrijp
jgonggrijp committed Apr 30, 2013
2 parents e0b1e11 + dbf6e62 commit 1558dd9
Show file tree
Hide file tree
Showing 4 changed files with 70 additions and 228 deletions.
4 changes: 3 additions & 1 deletion Authors.txt
View file
@@ -1,7 +1,9 @@
The Red Spider Project -- Authors.txt

(Please add your name at the top.)
(Please add your name at the top, if there's at least one file that
you edited but which your authorship isn't mentioned in.)

Alex Hammel
Jordan Brown
Harry Gilles
Julian Gonggrijp
29 changes: 11 additions & 18 deletions Dependencies.md
View file
@@ -1,28 +1,21 @@
Dependencies
------------

[The Red Spider Project](https://github.com/the-xkcd-community/the-red-spider-project)
[https://github.com/the-xkcd-community/the-red-spider-project]


### Git ###
Required for the setup script, `rsshell` and several commands:

In order to use Git with this project, you need:
- [Python 2.7](http://www.python.org/download/) (unixy systems should have a `python2` link).

- [Git](http://git-scm.com/), and
- a [GitHub account](https://github.com/).
Required for the `level_up` command:

[Git Immersion](http://gitimmersion.com/) provides a nice and quick
Git tutorial.
- [Python 3](http://www.python.org/download/) (unixy systems will need to have a `python3` link, on Windows it will be convenient to have [pylauncher](https://bitbucket.org/vinay.sajip/pylauncher) installed);
- [Tcl/Tk](http://www.tcl.tk/).

**Note**: if you just want to have a copy of the source code and
you're not planning to contribute in any way, you can do without Git
and just download a zip file from the project page.
Other dependencies:


### Programming languages ###

For now, only [Python 2.7](http://www.python.org/download/) is
required. In order to use the level_up command, you need [Python
3](http://www.python.org/download/) and [Tcl/Tk](http://www.tcl.tk/)
as well. If you want to try the `advbrowser` program, you'll also need
[PHP](http://www.php.net/downloads.php).
- Git, in order to participate (see [GitImmersion](http://gitimmersion.com/index.html) for installation and a tutorial);
- [PHP](http://www.php.net/downloads.php) for [zed0/advbrowser](https://github.com/zed0/the-red-spider-project/tree/advbrowser);
- [Visual C#](http://msdn.microsoft.com/en-us/vstudio/hh341490.aspx) for [BRNMan/master](https://github.com/BRNMan/the-red-spider-project);
- C++ on Windows (any compiler) for [xen-0/game-of-spiders](https://github.com/xen-0/the-red-spider-project/tree/game-of-spiders).
37 changes: 11 additions & 26 deletions Platforms.md
View file
@@ -1,17 +1,19 @@
This document lists the platforms that should be supported, and
outlines how to have them supported.
Platforms
---------

[https://github.com/the-xkcd-community/the-red-spider-project]

### Target platforms ###

Anything on branch `master` should be stable and support at least the
following platforms:
Anything on the integration branch should have been tested on a recent
version of each of the following platforms:

- Windows with cmd.exe (tested on Windows 7);
- Mac OS X with bash (tested on 10.6);
- Linux with bash (tested on Fedora 16).
- Windows with cmd.exe;
- Mac OS X with bash;
- Linux with bash.

Exceptions are possible, please discuss such cases with the others.
Exceptions can be made. "Testing" does not mean "fully tested and
stable"; sometimes it is only verified that the software behaves as
expected under expected circumstances.

Other platforms might work too, we just don't take effort to ensure
that. For example PowerShell on Windows works, though inconveniently.
Expand All @@ -20,20 +22,3 @@ to add tools like `python` to your PATH.

More platform support can be added if testers are available. Let us
know if you want to test for a new platform.


### Ensuring that your program supports these platforms ###

When you think it's time to merge your stuff into master, [submit an
issue to the main project on
GitHub](https://github.com/the-xkcd-community/the-red-spider-project/issues).
Tell us where we can find your branch and which platforms still need
to be tested. Also make sure that it's clear *how* to perform the
testing. When your branch appears all clear, merge it into your own
master branch and submit a pull request.


### Reporting failing platform support ###

If you find that something on the master branch doesn't support your
platform while it should, please submit an issue.
228 changes: 45 additions & 183 deletions Readme.md
View file
@@ -1,7 +1,7 @@
The Red Spider Project
----------------------

[http://the-xkcd-community.github.com/the-red-spider-project]
[https://github.com/the-xkcd-community/the-red-spider-project]


### Why ###
Expand All @@ -10,211 +10,73 @@ Because we like to combine our love for the xkcd comic with our love
for coding, and we want to share the experience.


### Who ###

Currently, "we" are mostly members of the [xkcd
forums](http://forums.xkcd.com). However, anyone is welcome to join
in.


### How ###

By keeping an ongoing project to which people can add programs at
will. By "program", we mean *any* program. It may be any size and it
may be written in any programming language, though preferably
portable. Most of the programs in our project will probably be
amusing, interesting, touching or a combination of those, either
because of the source code, because of the output, or both. Likely,
most programs will also be small. Anything is welcome except malware.

We put some emphasis on command line programs. The programs may be
interconnected with basic plumbing. We'll put some guidelines and
infrastructure in place to keep things smooth, as we see the need.
Other than that, it's basically liberty above all things!

For the impatient: fork the project, then

### When ###

We started in March 2012. In the first few months we spent most of our
effort on the infrastructure. In July we were treated to some splendid
logo designs and we got a homepage. In December we launched our IRC
channel. In the meanwhile several members have been working on various
subprojects, mostly in short bursts of activity.
git clone git@github.com:yourname/the-red-spider-project.git redspider
cd redspider
git remote add upstream git://github.com/the-xkcd-community/the-red-spider-project.git
git config branch.master.remote upstream
git config branch.master.merge refs/heads/master
./setup.py
rsshell

In the near future we may expect wiki content, a few big improvements
to the infrastructure, and an overarching role playing game, among
other things.
The project is like a small, self-contained operating system layered
on top of your actual operating system. People can add programs at
will. It's an open-ended process without deadlines or a final goal and
we're very open-minded.


### What ###

__License__: we have a liberal license which might strongly remind you
of the MIT license (that's not a coincidence). See License.txt for
more information.

__Platform support__: for the time being we just try to make sure
that our stuff runs on the most popular platforms. You'll need to
install some additional software, see Dependencies.md for more
information.

__Testing__: we use the issue tracker from GitHub to ask each other a
favour. See Platforms.md for more information.
**Note**: nothing is thoroughly tested, we just make sure that things
behave as expected under expected conditions.

__Branching__: `master` is our sacred branch. It's supposed to contain
only reasonably well-behaved programs (say: more or less stable,
portable and easy to quit). Nonetheless you're encouraged to merge
often into `master`. Do whatever you want in the other branches, but
please do observe some common rules of sensibility. For example, don't
merge everything into everything.

__Building__: currently we have a crude but effective setup script
that copies executable scripts to the right locations and pre-compiles
Python modules. In the future, we hope to use a more professional
build tool which can do that *and* compile things. Perhaps CMake.

__Directory layout__: we chose `src`, `include`, `doc`, `test`,
`build`, `lib`, `bin`, `config` and `work` (if the names don't tell
you what they're meant for, don't hesitate to ask). Programs will be
pooled enjoyably together unless a single program consists of many
files within the same directory (for some subjective value of "many"),
in which case we'll give it a dedicated subdirectory.

__Programs__: so far concrete work has been done on `rsshell`, which
launches a convenient environment for other Red Spider programs, as
well as on an xkcd comic fetcher, an xkcd comic regex searcher, an
adventure shell, an adventure web browser, a lines-of-code hacker
level calculator, a random text generator, an ascii art generator, an
xkcd comic wallpaper changing app and an advanced Conway's game of
life clone. More ideas are waiting to be implemented.

__Communication__: we have our little [thread at the xkcd
forums](http://forums.xkcd.com/viewtopic.php?f=11&t=81969) for
updates, discussion and archaeology, and there's the [issue
tracker](https://github.com/the-xkcd-community/the-red-spider-project/issues)
for bugs, requests and testing. In addition you can chat away at our
IRC channel (#redspider at irc.foonetic.net) or contribute to the
[wiki](https://github.com/the-xkcd-community/the-red-spider-project/wiki)
(soon to be more useful). For very specific things we sometimes
comment on each other's commits on GitHub.


### How to ###

Here's the place to find, submit or edit guidelines, rules of thumb,
suggested procedures, and so on and so forth.

A general rule of thumb: look at what the others do.


#### Obtaining the project ####
When you run `rsshell` the following commands are available to you.

Easy. Either download the source tree as a zip file from the GitHub
project page, or install Git (if you don't have it yet) and run the
following command in the directory of your choice:
- `xkcd-fetch`: Manages an offline xkcd comic database for you. Run
with `-h` for help.
- `xkcd-search`: Searches the database from `xkcd-fetch` for keywords.
Run with `-h` for help.
- `json-parse`: Manually inspect JSON files. Undocumented.
- `level_up`: An RPG-style lines-of-code counter which pops up a
"level up" message when you pass a milestone in a programming
language. Run with `-h` for help.

git clone git://github.com/the-xkcd-community/the-red-spider-project.git
The following commands are expected to be added soon.

Alternatively, if you plan to contribute to the project you may create
a GitHub account (if you don't have one yet), fork the project and
clone your fork to your computer instead.
- `summon`: A generic file/URL launcher which can handle any file type
your underlying system supports.
- `spider-life`: A Conway's Game of Life variant with two colors and
four different topologies for the universe.
- `xkcd-windows-wallpaper`: A Windows app which sets your wallpaper to
an xkcd comic of your choosing.


#### Installing the software ####
### Where ###

Run `./setup.py` from the root directory of your copy of the Red
Spider Project (you can leave out the `./` part in Windows). Read what
it says and follow the instructions.
- [Home page](http://the-xkcd-community.github.com/the-red-spider-project)
- [Issue tracker](https://github.com/the-xkcd-community/the-red-spider-project/issues)
- [Wiki](https://github.com/the-xkcd-community/the-red-spider-project/wiki)
- [IRC channel: #redspider at foonetic.net](irc://irc.foonetic.net/redspider)
- [xkcd forums thread](http://forums.xkcd.com/viewtopic.php?f=11&t=81969)


#### Running the software ####

Run the `rsshell` command that you installed with `setup.py`. After
that you can run any program from the `bin` directory by just typing
its name. Alternatively, you may also `cd` to the `src` directory and
execute development versions of the programs in there. Leave the
subshell with `exit`.


#### Creating something of your own ####

Pull in the latest changes to `master`, fork a new branch and hack
away. Take your time, we don't do deadlines. :-)

In source code files, please add something like the following in a
comment at the top:

Copyright YYYY __authors_of_major_contributions__
Licensed under the Red Spider Project License.
See the License.txt that shipped with your copy of this software for details.

Acknowledgements: X provided idea A, Y provided idea B.
Minor contributions were made by Z/by several authors;
please refer to the Authors.txt that shipped with your copy of this software.

Where `YYYY` starts off as the current year and
`__authors_of_major_contributions__` starts off as you, by definition.
More years and authors may be added later. The lines with
acknowledgements are optional, of course.


#### Integrating your stuff with the rest of the project ####

Finally, here's the really exciting stuff. You'll need to do some or
all of the following:

- If you wrote anything that should be copied to `bin` or `lib`
during installation, add it to lists at the top of `setup.py`.
- Push your branch to your public fork of the project.
- If you edited any Markdown files, check that they render correctly
on GitHub.
- Ask your fellow project participants for their opinions, if
relevant.
- Submit a test request to the issue tracker, for the platforms that
you couldn't test by yourself. See what happens.
- Once your branch works on all platforms, pull in the latest
changes to `master` and merge your own branch into it. Push that
to your public fork and request that it be pulled into the main
repository.
- Somebody will probably grant your request.

Once your branch has been fully merged into the master branch, others
can start using your work. Of course, nothing stops you from forking
another branch to add more features in the meanwhile!


#### Editing somebody else's stuff ####

First of all, please check whether the original author is currently
working on it. Next, create a new branch to commit your changes to.

If they're not working on it: edit, have it tested, have it pulled.
Business as usual.

If you're going to cooperate with them: add their public fork as a
remote, have them add your public fork too, discuss, and push/pull
your changes back and forth. Other than that, business as usual.
### When ###

Otherwise: you're about to create a parallel alternative version, so
be aware that something special will need to be done before you can
merge your changes. Perhaps give your variant of the program a
different name.
We started in March 2012. In the first few months we spent most of our
effort on the infrastructure. In July we were treated to some splendid
logo designs and we got a homepage. In December we launched our IRC
channel and in March 2013 the wiki took off. In the meanwhile several
members have been working on various subprojects, mostly in short
bursts of activity.

Depending on the nature of your contributions, you should probably
either add your name to the copyright notices of the files you edited
or include it in the Authors.txt. For program source files, a guiding
question could be the following: "Did I contribute to the program
logic?"
In the near future we may expect a few big improvements to the
infrastructure.


### Credits ###
### Who ###

Julian coined the idea, qubital set up the GitHub repository, Neil
wrote most of the initial infrastructure code and Joey designed the
logo proposals. Please also refer to the copyright notices in the
source files and to the Authors.txt, which lists all the authors who
decided not to add their name to some file they edited.

Please add your name to the Authors.txt if it isn't in there while it
should.

0 comments on commit 1558dd9

Please sign in to comment.