Update Github contributions instructions

[rogerhoward]

Our current Github flow doesn't require any particular adherence to naming conventions - it's too loose. Let's agree on some basic standards.

[rogerhoward]

1 - Everything must start with an issue...

Issues should have useful, concise titles and enough of a description to understand the scope of the issue.

[rogerhoward]

2 - branches should link to individual issues, and be named using consistent syntax:

bug/#123-abbreviated-issue-title feature/#123-abbreviated-issue-title enhancement/#123-abbreviated-issue-title

[rogerhoward]

3 - a branch should represent an atomic change

...merging the branch to master should not break anything in master. A branch should be fully testable and functional once finished - I should be able to deploy any given branch and have a functional site.

[rogerhoward]

4 - pull requests may not be merged by the requester. Ever.

Even me...

[rogerhoward]

5 - once a pull request is merged, the branch should be removed.

Just basic cleanup.

[rogerhoward]

6 - PR's should use Github keywords so they automatically link to/close related issues.

For reference: https://help.github.com/articles/closing-issues-via-commit-messages/

[karimamer]

:+1: on this process and will like to add Good commit messages serve at least three important purposes:

• To speed up the reviewing process.
• To help us write a good release note.
• To help the future maintainers of code and coffee

Structure your commit message like this:

From: [[http://git-scm.com/book/ch5-2.html]]

Short (50 chars or less) summary of changes

More detailed explanatory text, if necessary. Wrap it to about 72 characters or so. In some contexts, the first line is treated as the subject of an email and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two together.

Further paragraphs come after blank lines.

• Bullet points are okay, too
• Typically a hyphen or asterisk is used for the bullet, preceded by a single space, with blank lines in between, but conventions vary here

DO

• Write the summary line and description of what you have done in the imperative mode, that is as if you were commanding someone. Start the line with "Fix", "Add", "Change" instead of "Fixed", "Added", "Changed".
• Always leave the second line blank.
• Line break the commit message (to make the commit message readable without having to scroll horizontally in gitk).

DON'T

• Don't end the summary line with a period - it's a title and titles don't end with a period.

Tips

• If it seems difficult to summarize what your commit does, it may be because it includes several logical changes or bug fixes, and are better split up into several commits using git add -p.

References

The following blog post has a nice discussion of commit messages:

"On commit messages":http://who-t.blogspot.com/2009/12/on-commit-messages.html

[torch2424]

I agree with everything said above. However, I feel like @rogerhoward 's #2 is a bit strict. I feel like a branch name should be anything that represents an issue or topic you are trying to contribute. Having a forced naming convention makes it feel less open to me. But that's just my opinion

[karimamer]

@torch2424 makes it easier to navigate branches and to maintain all branches. say your adding sign up page that would be feature/#123-add-sighn-up-page so it doesn't really strict you unless i am misunderstanding your comment

[torch2424]

@karimamer You understand me, and yes I would agree it makes it easier, but I was just explaining why I dont implement it. but if that is what's going on, it's completely fine :)

[torch2424]

Transferred from #46 : I feel like we should clean up our branches. Currently we have alot of stale branches. I noticed alot are member page branches, and those I feel like should be deleted, if the member would like to update their page, they could easily create a new branch.

this would also prevent user from push old master code on accident.

This rule was also implemented in our new readme in #50

[rogerhoward]

That's one issue I feel quite convinced on, having experienced both. Which of the two points in #2 are you objecting to, and what are the downsides?

a) Linking branches to issues b) Using a naming convention

Linking branches to issues is essential - it enforces the "don't do it if you haven't opened an issue" guideline, which I also feel strongly about - it helps avoid surprise branches ("i just did 2 weeks of work on this and you don't want it! boo!") by inviting discussion first. It helps tracking the scope/purpose of a branch by connecting to an issue.

Using a naming convention - honestly, this seems like a no-brainer to me. Got the issue number? Trivial to find a branch. Using standardized naming? Helps sort branches in obvious order. Avoids troublesome branch names.

I really think that's a low barrier to entry and the benefits are huge.

As always, I'm open to being convinced otherwise...

[torch2424]

@rogerhoward and @karimamer you have convinced me otherwise, I was earlier reffering to strict naming conventions, but after hearing both of your words I understand and agree :)

[torch2424]

Also, is there a way to rename a branch? Once they are created they is no going back correct

never mind: https://gist.github.com/lttlrck/9628955

[karimamer]

44 let's add github cheat sheet to code and coffee website

[rogerhoward]

Please note my comment on the other issue, copying here to make it explicit:

One critical note - we cannot just incorporate content others developed without their permission, or at very least by using content that has an explicit license allowing us to do so. If you want to incorporate that Github cheat sheet, please contact the author and ask him how to proceed.

If you just want to link to it, that doesn't require permission.