civicdata.github.io
civicdata.github.io copied to clipboard
civicdata
expand contribution guidelines
note typical workflow we use, as well as file naming conventions, specifically:
- all lowercase file and folder names
- kebab case naming (no underscores)
- branch naming conventions
Right now, the CONTRIBUTING file has nothing in it. I'm working on writing a quick technical guide to getting the project up and running. Is there anything else I can throw in this documentation while I'm in there? I basically want to give people a guide to installing Ruby, Rails, Jekyll, and Bundler based on the documentation that already exists at:
- gorails.com
- jekyllrb.com
Does this even relate to this issue?
@am1983 Some of that will need to be in an updated readme file but if you're approaching it from "how to add more " and not "how to make this work locally" then it makes sense to include it. There may be some overlap between the two files, and that's fine.
@jessetylermullins It was a mix of both, tbh. I want to give new contributors a place to go to get the instructions on setting it up and also have a discussion about how to contribute in terms of workflow. IMO, it should look something like clone, branch, "do work", test, push, PR...
I've created branch update-contributing-documentation as a place to start the work. I've added a basic outline but it definitely needs work before a PR.
I can definitely see where this technical outline should probably work itself over to the README.md.
@am1983 I would say "refer to the readme on how to set this up locally" with a link, and only pull out what's essential. The comment on clone, branch, do work, test, push, PR - that's what should be in this doc.
Refer to my comment above if you want to include those things while you're working - and we default to the Atlassian Gitflow Workflow so I would suggest referencing that as a baseline.
That sounds good, Tyler. I'll sort those changes out and spend some more time on both the README and CONTRIBUTING files in the coming days. Let me know if there is anything else you can think of that may be useful in those files.
On Feb 15, 2018 4:36 PM, "Tyler Mullins" [email protected] wrote:
@am1983 https://github.com/am1983 I would say "refer to the readme on how to set this up locally" with a link, and only pull out what's essential. The comment on clone, branch, do work, test, push, PR - that's what should be in this doc.
Refer to my comment above if you want to include those things while you're working - and we default to the Atlassian Gitflow Workflow https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow so I would suggest referencing that as a baseline.
— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/civicdata/civicdata.github.io/issues/77#issuecomment-366069660, or mute the thread https://github.com/notifications/unsubscribe-auth/AJQAZ0LVRuVzCQwYjEKxcOO1a0fUnFl-ks5tVKN1gaJpZM4SF4OT .
Would love to work with you all on this. For this repo in particular, we're actually using a simpler workflow called GitHub Flow.
We've also went an extra step and locked down the Master branch so there are no direct merges to Master, which is always deployable, before they're ready.
I suggest structuring work in a typical OSS fashion too. So for this repo, work should be done not in branches directly on this repo by people who want to contribute. That requires managing who is and is not part of the repo and organization too. What we should do is a typical forktoyouraccount-branch-"do work"-test-pushtoyouraccount-PR.
Though I'm open to suggestions otherwise.
@thebouv I'm with you - not everyone should be a direct contributor. Should anyone? For instance, when I started working on this, I created a branch on our repo. Should I roll that back, fork to my account, branch, then do the work? Where do you think we should draw the line? (Just curious. I'm down for whatever, tbh).
Just an update: Life has happened. I haven't forgotten about this - I've just been over extended. If anyone else wants to jump in to help, please feel free. I'll jump in when I can.
Raising this issue back up. Can we get a basic document describing how people should contribute?
