search

rubyforgood / habitat_humanity

MIT License
6 stars 13 forks source link

Add onboarding documentation #93

Closed leesharma closed 8 years ago

leesharma commented 8 years ago

Resolves #92

Major changes are as follows:

This PR is parallel to some additions to the project Wiki for details that don't need to be included in the project source code.

leesharma commented 8 years ago

I can't sleep, so here's a pull request.

What do you all think about the README information? I'm planning on putting other details (git flow, development tools like guard, etc.) in the wiki. Anything else that needs to be on the front page?

What about the contribution guidelines? Too loose or tight? Are they confusing at all?

jdsayle commented 8 years ago

Hey all,

(Sorry I couldn't make it out yesterday!) @Lee, I think that the contribution guidelines/readme are clearly written and easy to follow. Only thing I'd say - and I know that it's a WIP at the moment - the wiki is fairly barren. Other than that . . . WOW nice work!

Just my 2 cents, -JD

On Thu, Aug 4, 2016 at 1:56 AM, Lee Sharma notifications@github.com wrote:

I can't sleep, so here's a pull request.

What do you all think about the README information? I'm planning on putting other details (git flow, development tools like guard, etc.) in the wiki. Anything else that needs to be on the front page?

What about the contribution guidelines? Too loose or tight? Are they confusing at all?

— You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub https://github.com/rubyforgood/habitat_humanity/pull/93#issuecomment-237459732, or mute the thread https://github.com/notifications/unsubscribe-auth/AM9dB2Uds6fUwGAGtCd0AU9PubuiW6PNks5qcX8pgaJpZM4JcXRn .

leesharma commented 8 years ago

@jdsayle Thanks! I'll be fleshing out the wiki more today–yesterday was just a skeleton.

Also, to everyone: I have some questions about our git workflow.

So far, we've been doing a branch-based workflow with work being done on <name>/<short desc of feature/bug> (ex. robb/actually-send-mail). However, this breaks down when someone new wants to join the project–they can't claim issues or make new branches.

How do we want to handle newcomers to the project? Keep the same "internal" workflow and have newcomers use forks to start? When should they get repository access, and who has the permission to grant it?

bjmllr commented 8 years ago

These are great questions and they might be questions we want R4G to have an opinion on, just so we don't have to wrestle with them again every year. I'll share my thoughts.

I like forks. I think the single fork works better for groups where everyone is committed to the project and/or there is a certain degree of rapport (the "core team"), and multiple forks works better for newcomers and occasional contributors. Some of us have that rapport and/or commitment, but most OSS contributions are just spikes, so I think it makes sense to use both.

If someone outside the core team wants to claim an issue, I think it's enough to put a comment saying "I'll take this on" in the issue. This is probably worth calling out in CONTRIBUTING.md.

Re joining the core team: Most OSS contributions are just spikes, so I think it makes sense to invite someone in after they've shown that a pattern of commitment to the project's success. Also, a special responsibility of the core team is to review and merge contributions, so I think it makes sense to prefer people that have demonstrated they'll do this effectively. Also also ... hopefully this doesn't come up, but not everyone will meet our standards of niceness/good citizenship/conduct/etc, and we're representing R4G as members, so let's try only to invite people who will.

Generally the core team decides who joins the core team (subjectively, to account for the subjective nature of the criteria in the previous paragraph). I added @leesharma unilaterally, maybe I should have asked someone else first, though I don't think anyone would have pushed back. On the other hand, for a project and team this size, I suspect the stakes are low enough and the trust is high enough for the team leader to make those decisions.

I agree with all the file changes in this PR, and the wiki info looks good too.

leesharma commented 8 years ago

I added the line that @bjmllr described (about claiming issues) and filled in the wiki. Is there anything else to add/edit for in-repo documentation, or is this ready for merge?

leesharma commented 8 years ago

@atzorvas: that makes sense–I'll consolidate the rake tasks.

leesharma commented 8 years ago

Anything else to add/change, or is this ready for now?

jdsayle commented 8 years ago

Hi All,

I've been out of the loop for a bit (ie - sorry if this was addressed but didn't see it in comments anywhere . . . ) I get a 404 error when clicking on the Contribution Guide links in the wiki. If this is a known issue, perhaps just putting (WIP) in text next to the links and on the Contribution Guide page will work for now? At least until until we have that page populated with content.

Other than that small thing I think that the wiki is clearly written and covers everything I'd want to know or see.

-JD

On Tue, Aug 9, 2016 at 6:40 PM, Lee Sharma notifications@github.com wrote:

Anything else to add/change, or is this ready for now?

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/rubyforgood/habitat_humanity/pull/93#issuecomment-238714610, or mute the thread https://github.com/notifications/unsubscribe-auth/AM9dB3FEnPd5fHvsL9mXntJyPUgv4FKtks5qeQHxgaJpZM4JcXRn .

leesharma commented 8 years ago

Oh, forgot to mention that! It links to the location CONTRIBUTING.md will be when it's merged into master. We could put "WIP" for now, but if the changes are ready for merge anyway, I'd push for that.

leesharma commented 8 years ago

Actually, I just went through and changed the links to point to the lee/onboarding-docs branch CONTRIBUTING.md for now (so there should be no more broken links); I can change them back when this does get merged.

bjmllr commented 8 years ago

I'd say this is ready to merge.

leesharma commented 8 years ago

Awesome!

Could someone else hit the "merge" button? I don't want to self-merge, especially since this PR includes warnings against merging your own PR.

robbkidd commented 8 years ago

👍

I'll bungee in here, push the button, and bungee away again.

gif-keyboard-2700566754705130166

leesharma commented 8 years ago

:heart:

(Sadly, there's no bungee emoticon on GitHub.)