If you'd like to contribute code to the TinyMUSH 3 project, here are some guidelines. The less work it is for the core group of maintainers to integrate your patch, the more likely it is that your patch will be accepted in a timely manner. Consequently, for both your sake and ours, we encourage you to follow the guidelines below.
- The project has a patch tracking system on its SourceForge home page.
Please submit patches to that system, as well as posting notification
on the mailing list.
- Any code that you contribute to the project that is intended to be
part of the main server (as opposed to a standalone module) must be
licensable under the Artistic License that we use. Contributions
for incorporation into the core should not require a separate license;
we'll consider anything that absolutely must have its own license
(which must still be compatible with the Artistic License) on a
case-by-case basis.
- Please include appropriate help text with your code. This will both
help everyone understand what you are trying to achieve, and spare
someone else from needing to write the documentation.
- If you are implementing a new feature, please check to see if it exists
in PennMUSH or TinyMUX 2. If it does, don't break compatibity unless you
have an extremely good reason to do so; include an explanation of why
you decided to do that.
- Make sure to patch against the latest sources in CVS. It will strongly
decrease the likelihood that your patch will conflict with a recent
or planned change.
- Read as much of the relevant existing source as you can. Try to use
the existing stylistic conventions, infrastructure functions, etc.
where possible. If you've come up with a much better implementation,
rather than just using it in your own code, change the relevant
infrastructure function, so everything else gets the benefit of
your improvement.
- If you are implementing something similar to a feature that already
exists, do not duplicate big chunks of the existing code. Refactor,
so you can reuse code without having to duplicate it.
- Comment your code!
- Please try to conform to the existing style of the code. We use an
indentation style that is similar to K&R, with either an eight-space (tab)
or four-space indent, i.e.:
for (foo = 0; foo < x; foo++) { /* body */ } - For historical reasons (older compilers unable to handle ANSI C),
we use K&R-style function declarations, with macros that handle declaring
arguments ANSI-style if the compiler supports it. Thus:
char *get_foo(player, cause, key, target) dbref player, cause; int key; char *target; { int i; /* body */ }or, for a function that takes no parameters:
void NDECL(match_foo) { /* body */ }or for reference declarations:
extern char * FDECL(get_foo, (dbref, dbref, int, char *)); extern void NDECL(match_foo); - Name things in a useful and non-profane manner. Variables and function
names are all in lowercase, with an underscore used to separate words.
Constants are in all uppercase. Macros typically begin with a capital
letter, with the rest of the macro name lowercased, with words separated
by underscores. Macros are occasionally declared all in lowercase or
all in uppercase (generally when representing functions, as opposed
to logic expansions and the like).
- Use the macros in alloc.h for allocating and freeing memory. Make use of
XCALLOC to allocate arrays of structures (it avoids alignment issues).
Use the buffer pool management (lbufs and the like) for strings, rather
than declaring character arrays or directly malloc'ing space for strings.
When you test your code, make sure you do a @list buf, and ensure
you're not leaking any buffers.
- Do not declare a variable static unless you have ensured that there
aren't any cases where it can be accidentally overwritten (through
nested calls, for instance).
- When you are writing something into a buffer, make use of the safe_str() family of macros, if you possibly can. Don't use sprintf() unless you know that it can't possibly overflow the space allocated for the string.
Created 10.03.04 | Revised 06.06.06