Draft Contributing Guide

contributing.md

Contributing to EpicEditor

Suggestions for contributing to EpicEditor. For feature and bug fix contributions we try to follow Vincent Driessen's git branching model. No fix or feature is too small. Thanks for contributing.

Issues

Before submitting a bug report or feature request, please check to make sure it hasn't already been submitted. You can indicate support for an existing issue by commenting on that issue. When submitting a bug, please include any details necessary to reproduce it (e.g. browser, OS etc). And if you're feeling frisky, including a failing test is super helpful.

Pull requests

If you are fixing a bug you found or adding a feature, please report the bug or feature and take note of the ticket number. After fixing the bug use the following template for your commit messages:

$ git commit -a -m "Ticket #[ticket number] - Fixes foo"

This makes it easier to track stuff down later on.

Requirements

We rely on Jake to manage tasks, foounit for tests and JSHint for linting. All of these run on NodeJS and can be installed via npm as follows:

$ sudo npm install -g jake foounit jshint

Flow

1. Fork the project.
2. Create a topic branch e.g. git checkout -b epic-bug-fix git checkout -b new-feature.
3. Add tests where possible.
4. Implement your feature or bug fix. Changes should be made to the src/ files, not the built files in epiceditor/.
5. Run tests: jake lint and jake test.
6. Rebuild: If everything is passing, jake build.
7. Commit and push your changes. Try to reference the associated ticket number in your commit message as noted above.
8. Submit your pull request - ideally targeting the development branch

A core developer will add a black label with a version number where this was pulled in, i.e. if the fix was included 0.1.1 then we will add a black label with 0.1.1 and close the ticket. Closed tickets do not mean they are in the release!

Nice, this looks awesome :) I like the Rails admin how you can contribute section.

I got the idea from Yammer since it's being worked on by tons of people and the template above works great. The template is for small tickets. For large features we usually have a topic branch of the feature and that's probably fine here too. We use git flow so all our feature branches look like feature/foo-bar and If you think it's good too, I think just doing feature/your-feature would work fine.

The ticket number stuff is merely to reference reported issues. So, lets say down the line there's an issue with key shortcuts they could go through the issue tracker and see ticket #123 and then do a git log for #123 and do diffs on it and see all associated commits for it.

This looks pretty sweet. You should throw this into the wiki!

Oh nice! Is this what you were referring to nvie/gitflow? If so I dig it! I'll definitely look into adopting this at work as well.

A few questions:

1. Do you want to go the gitflow route and use a develop, feature, hotfix model -- with master only containing releases. (git flow looks good to me, but you have more experience and would know if it's a good fit here)
2. Do you want to include a list of supported browsers, i.e. browsers that should be tested against for css fixes etc?
3. Are you interested in moving the css out to src/ and compressing that on build as well?

1 - I personally love git flow and I wanted to put it into EE, but it'll make the barrier even larger to contribute I think. It's also confusing to a lot of people. We've had about 3 accidents at work where people have totally fucked up our branches by doing wrong merges because they didn't ask questions and we had to destroy our working branch (develop) and redo our work (because with git flow you delete feature branches when you're done).

What do you think? You think we should lean towards easier contributions or just what we want?

2 - Yes. To start: IE8 and 9 as well as Firefox and Chrome latest. I'm thinking for IE7 we have a lighter version that saves less frequently (instead of 100ms) and doesn't do fullscreen. I think tho IE7 should be worked on as a "feature" because I'm guessing we're going to hit a lot of issues.

OscarGodson/EpicEditor#3
OscarGodson/EpicEditor#4
OscarGodson/EpicEditor#5

As for mobile, I already had concepts on a iPad/tabel and iPhone/smartphone versions as well. I don't have an Android phone, but @dadambickford could port the iOS styles to Android.

OscarGodson/EpicEditor#27

3 - Yes, for sure, I was thinking about this last night. However, we can't merge the CSS files as we need to be able to allow different CSS files per iframe (base, preview, editor) and I'd like to be able to setup an API call to swap out themes dynamically with the preview() method. I'd love to compress them all to single liners or however we can tho.

Ahh gotcha on the gitflow concern. Maybe the model could at least be loosely applied - not necessarily using the automated utilities - just the model itself if that makes sense. I'll update the gist to reflect.

Yeah. A looser model would be great. Master would stay with releases as it is now, but have a development branch of some sort and feature/foo-bar for features.

I updated the wiki with a few of the things we talked about, feel free to clean it up as you see fit and let me know if you have any questions or concerns.