Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
138 lines (87 sloc) 8.3 KB

Contribution Guidelines

Please hold off on the feature requests for now; the project is still in its infancy, and as you can tell by the milestones and feature to-do list in the README, there is plenty to grapple with as it is right now.

Bug reports and suggestions immediately relevant to the current feature and issues list are much preferred. But all rules have exceptions.

“I found a security flaw. What do I do?”

Use the contact information in my GitHub profile to get in touch personally. Proofs of concepts are, of course, always ideal.

Because Pony Forum is not hosted as a service in one place (AKA SaaS), issuing a security patch to this GitHub repo does not “fix” the problem for forum owners. They still have to be notified of the patch, after which they can update installation to the newest, patched version.

It is (therefore) not a great idea to publicize a security hole or discuss it in public, until people have had a chance to patch it. Facebook can patch its entire platform, whereas I can’t patch all installations of Pony Forum in one fell swoop.

Whenever a security flaw is found and patched, a call to update Pony Forum installations will be made on the official blog and Twitter profile. At which point after that it is O.K. to discuss the security hole in detail with proofs of concepts I yet to make up my mind about.

The future plan is to create an in-forum notification for administrators that lets them know about the available patch as soon as possible to minimize the time from a security patch is issued to its installation across forums powered by Pony Forum.

Basic Guidelines

  1. Your code must work in browsers Opera, Chrome, Firefox, Safari, and later, saner versions of Internet Explorer.

    I do not suffer smartasses who only submit stylesheets with vendor prefixes for the two or three browsers they like, because all the others “suck”, and “only stupid people use those browsers”.

    There are even people who do the job for you.

  2. Limit your pull requests to a single issue.

    I consider this a guideline more than law of the land. There will probably be exceptions where it makes sense to bundle related issues, but keep this guideline in mind as a rule of thumb.

    When filing a pull request, keep the following in mind, too:

  3. Limit your commits to a single type of improvement:

    To reapply rule #2 to commits and not just pull requests, do not merge commits with different purposes such as spelling, newline, whitespace corrections, as well as any other improvements.

    This also improves the quality of your commits significantly.

    Generally, it is better to submit your changes in a single commit. If you know your git, you should squash several commits into a single one. This way, it will be much more manageable for everyone.

    To all rules there are exceptions, though.

  4. Include screenshots, whenever relevant.

    Use GitHub’s built-in image attachment system instead of services like Imgur and Minus.

  5. Respect the concept of “officially supported”:

        Stacks      |       Officially Supported
    

    :------------------|:--------------------------------- Operating Systems | OS X and Ubuntu (latest versions) Python | 2.6 and 2.7 Databases | PostgreSQL

    So if something does not work on your Windows installation, it should come as no surprise. Do not be discouraged from contributing solutions to make Pony Forum compatible on more stacks and platforms, though. It is the intention to make Pony Forum available on Windows at some point.

Pedantic Style Guidelines

  1. End all files in a newline. Exceptions are files where it affects the execution:

    • .txt files
  2. Line endings must be Unix line endings.

  3. Tabs must be four characters of space in the following filetypes:

    • .py
    • .html
    • .txt
    • .mdown
    • sh scripts

    I am currently undecided on whether to use 2 or 4 spaces for a tab in .css, .js and .json files.

  4. There will eventually, but not currently, be some clearer guidelines for when and when not to use single and double quotes. Be mindful of how you use them and try to use them consistently in your commits.

  5. Avoid lines longer than 78 characters as a rule of thumb.

In general writing, I use my own variant of the Oxford style.

I only mention this to pre-empt annoying pull requests for asinine corrections. It is not something you should concern yourself with when contributing.

Tips

If you use Sublime Text 2 as an editor, you can adjust your settings to conform with the Pedantic Style Guidelines(TM):

Conforming with 1

"trim_trailing_white_space_on_save": true,
"ensure_newline_at_eof_on_save": true

This makes your code fit the guideline automatically, and removes the need to worry about cleaning up your code and complying with the Pedantic Style Guidelines(TM).

There is a rub, though; you have to turn off "ensure_newline_at_eof_on_save" when editing the files exempt from the newline rule.

Conforming with 2

"default_line_ending": "unix"

Conforming with 3

"tab_size": 4,
"translate_tabs_to_spaces": true

Sublime Text 2 will again make your code conform with the guidelines automatically.

It will however not convert existing non-space tabs to space-based tabs. This should not be too much of a concern in an instance where you are editing the code of this project, though.

You can find my own Sublime Text 2 user settings in this gist. Maybe it can be of use to you.

Issues

This project is in its infancy, to say the least. Because of this, inundating me with feature suggestions that will have to be implemented six months from now will mainly serve to clutter the issues, or worse, clog it, rendering it useless.

This preliminary phase is focused on implementing what can best be described as basic features. What constitutes a basic feature can be hard to define, but for the time being, I defer to your own best judgement.

The most important issue is to iron out any bugs that may exist in the current code—which is not at all hard to imagine, considering that I haven‘t had any time clean up my code.

Pull Requests

Pull requests will be submitted to a high level of automated scrutiny at a later time, but for the time being, any pull request must pass the very lenient Travis CI test. The .travis.yml file can be found here. You will also receive an automated response to your pull request that will tell you whether you submitted build fails or not—but again, only on a very basic level.

If the build fails, it is expected that you will amend the error—assuming you are able—to expedite the process.

I will later create Travis tests to strike a balance between catching errors, before they enter the code, and penalize contributors for pedantic reasons. Nevertheless, the script exists to catch errors and make it more effortless and less time-consuming for everyone involved to contribute to the project.

And for the love of Linus Torvalds, write descriptive, succinct commit messages with appropriate spelling and capitalization of the first letter when applicable in a way that does not make people mistake you for a bot.

If you submit a bug fix, consider writing a unit test that would have detected it in the first place, if appropriate.

Finally—and Most Important

Please don‘t take it personally, if your suggestion or contribution is rejected. It is incredibly strenuous and time-consuming to manage a project of this magnitude without succumbing to feature creep, design by committee, and people who feel entitled to appropriate the project and make the decisions. Such users are welcome to fork the project and take it in their own direction.

Last, but not least: we are all fallible, and I am going to fall victim to my own guidelines time after time after time. I do not expect anyone to always get it right; it’s not like we stop coding, after fatigue and madness set in.