nelsonic
commented
7 years ago @Cleop good question! It's always a balance between communicating effectively and "bureaucracy". We want to have guidelines we expect everyone to follow because it prevents miss-understanding in the community. If someone spots an opportunity for improvement in a README file (e.g: a typo correction or clarification which will help newcomers) they can still share the improvement in two simple steps:
- inform the community so that everyone is aware of the issue/improvement and it can be "validated". Often someone does not have time to "fix" the issue immediately so simply reporting it is a good start; they can either come back and fix it later or someone
elsecan pick it up. - fix the issue in a Pull Request that references the issue.
We think these two steps are vital for communicating. We've had several instances of where people have "fixed" things that didn't need to be fixed or two people have made the same change and one person's work is wasted.
Remove the "WIP" from your PR when you think its contents are useful to others. I often don't manage to "finish" adding "all-the-things" to a PR and simply "draw a line" so I can get on with other work while not leaving the PR in limbo if it contains something useful.
It's often better spread the changes over more than one PR so that others can benefit from your work sooner. only when writing code that would be "useless" until it's complete would I advocate a single larger PR.
Hope that answers your question. if not please let me know! 👍
I read #4 and wanted to ask about issues/PRs for READMEs.
- What kind of issues should you be creating when editing a README? I've raised specific ones like: https://github.com/dwyl/learn-elixir/issues/39 but other than that, a lot of it is a more general 'edit', should you create an issue saying 'needs edit'? Should you create multiple if it takes you a few rounds of editing before it's ready?
- How often should you PR when doing a broad edit of a README that may take some time? I have an open PR with WIP, is that sufficient? Should I only merge when the entire thing is complete?
I'm currently working on READMEs for daydream/ elixir (when I can) but given that it's written content (and the issues are more subjective in length/completion) as opposed to code, I'm finding it hard to know when to remove the WIP tag off PR's.
@nelsonic what do you think given your comments in #4 ?