@jesse: I’m starting to get a reasonable understanding of pieces of Kaleidoscope now, and I want to submit some changes to the code (though mostly what I have in mind right now is documentation in the form of comments). Do you want to give us all some guidelines for how you’d like pull requests to be submitted? For example, should there be at least one Github issue that’s addressed? Do you want to make sure that they’re as small as possible, for ease of review and integration, or would you rather have a few more significant change sets to minimize the overhead of administrivia? Or would you rather have people just be bold and have at it?
I feel quite inhibited by the feeling that I’m invading someone else’s work here, and I also don’t want to get in the way of more important things that you need to devote your time to, but I can also see a few minor improvements that I could make, and I’d love to help make it better.
I don’t generally require open issues in advance of pull requests. If you’re resolving an issue, mention that in the commit message. If you’re starting in on a project and want a place to talk about it, by all means feel free to open an issue, but don’t feel obligated to do so.
Each commit should be one logical change. Maybe that means “documentation of one function” or “documentation of a set of related functions” or “one bug fix”
Commit messages should describe the “why” of a code change. (Though for a documentation-only change, the ‘why’ is typically obvious and a little less critical than a code change.)
Personally, I find lots of tiny pull requests to be less overhead than one massive pull request.
For code changes, it means it’s easier to test a change in isolation.
For doc changes, it’s just a little bit clearer.
And either way, a PR I can review with one hand while trying to stop my son from trying to “help” with the review is a PR I’ll be able to act on faster.
While @algernon and I have written most of the code to date, my goal is that there be a vibrant community of folks contributing to Kaleidoscope. I’m a believer in having a single project leader who sets the ultimate goals, the direction and the community standards. (Ala Perl’s Pumpking or Python’s BDFL) But if that individual isn’t building a community and accepting of contributions that don’t conflict with their goals, then the project will probably not really grow and flourish.
Put another way: Accepting contributions is high on our list of most important activities. I won’t be shy about telling you if a particular contribution or proposal doesn’t fit with what I want to see in Kaleidoscope. If I don’t also tell you why I feel that way, it’s always ok to ask.
I also won’t be shy about asking for revisions to a PR that doesn’t feel quite right yet. I tend to be pretty pedantic about naming. (Even if we already know that my taste in naming doesn’t always feel right to you)
I might sometimes not respond quickly to a pull request, especially from a “known” contributor. I try hard to respond faster to newbies or to first pull requests, though I’m not always perfect. If something is languishing, feel free to reach out to me, either on the PR’s comment thread or by mail to check in.
Thanks, @jesse; knowing all that makes it much easier for me to go ahead and submit changes, especially since I generally feel the same way, particularly about the preferred size of change sets.
One other thing holding me back, though, is lack of hardware with which to verify changes. I’m planning to go ahead and try a few isolated things that I’m pretty confident in, but I’m going to make it very clear in the PR comments that some testing is needed to verify. I hope that works okay for now, but you should definitely consider me someone who doesn’t need immediate attention when it comes to any of these things. And once I do have the hardware, that won’t be an issue.
As a data point, I started contributing - sometimes significant changes - way before I had access to hardware. Sometimes I broke things, sometimes very badly. But that’s ok, there are now plenty of people who can test new code, and a good few who are willing too. I’d consider that as a challenge (I certainly did, and it was a lot of fun). Even when I had hardware, there were sizeable parts I wrote at work during lunch break, without access to the prototype. You get the hang of it soon enough.
I found it extremely rewarding that I could contribute without hardware. It was a good challenge, and a joyful feeling when Jesse told me it works, and merged it.
Mind you, we all work differently. What was a challenge for me, might be a burden for someone else.
