Contribution Guidelines

[stianhoiland]

This last release cycle has tested me. Since last release cmdtab has gotten a few good contributions and I have finally attended to them. I've never managed a collaborative project before and attending to this has not been easy for me.

• It's been hard to wrap my head around how people have thought that their changes fit with the current state of the project and how that again fits with my vague and morphing plans for its future
• People have had the same ideas and implemented them differently. Most of the time it's not satisfactory to just choose one over another as each have their merits
• The same goes for myself: Either inspired by contributions or not, consciously or not, I make changes that overlap with others' contributions
• Sometimes the ideas are good but the style is not to my liking. I don't want to chaperone, nor do I want to accept patches I don't like

These issues make it hard to coalesce and correctly attribute changes, which I take very seriously: If you contribute something good to cmdtab, you deserve full credit for it. Ideally I would just merge pull requests and that would be sufficient credit, but it's not so easy: Most of the time pull requests are not factored to my liking, and sometimes changes make it into the codebase with myself as author but really was inspired by or downright copied from another contributor.

It's given me something to chew on and here's how I'm moving forward with cmdtab:

If, at the time of writing, you have any open pull requests, I will most likely not accept them in their current form. Chances are that I will in time integrate your pull request in my own changes and I will credit you as best I can in commits, release notes, etc. Crediting you is important to me. I will also close the pull request when that time comes.

I consider this less than ideal for both you and me. Therefore something should change.

---

Contribution Guidelines

Going forward, I will advice contributors to factor their pull requests VERY neatly and focused. Be very, very aware of your scope if you want your changes accepted. Number of commits don't concern me as much as scope, but I do prefer a succinct and condensed history. I don't need to see how you worked, but if a feature evolved over a couple of commits, so be it.

Contributing code is not the same as writing code as usual and then also sharing it. Make it easy for me to review scope and code.

Also, let me comment on pull requests that amount to "here's my personal fork". Thank you for sharing your code; someone will come along with the same needs as you and use some or all of it in their own personal fork. On the other hand, there is little chance of getting it mainlined as-is. Not because the changes aren't good, but because it's admin hell.

In short, make sure your pull requests add, change, or fix only one "thing" (ex. #14, #17). Make other pull requests for other "things". Many pull requests makes it easier for me to communicate changes I require before accepting. Many pull requests is good.

---

With all that said, if you currently have any open pull requests and want to open new pull requests which refactor your old one(s) to comply with the above guidelines, feel free to do so. Otherwise, don't worry; I will continue as explained and you are likely to be credited, though not merged.

Thank you for your attention and contributions!

[stianhoiland]

@german-one @itsmaybetokyo @prechelt I'd appreciate it if you would read this issue. Thank you :)

[german-one]

Thanks for the clear advice, Stian. Appreciated!

Speaking only for myself:
You know I already closed a PR because it's hard to keep track if it's like an entire refactoring of the code. Nonetheless, it's still there and you can take a look at any time to copy parts out of it or just take over some ideas. My intention is only to improve the app for a better user experience. I couldn't care less about GitHub activity statistics or credits in release notes.
However, what I'm interested in is getting feedback about the contributed code. I'd like to know if it is helpful or not, if it meets your visions about the app or not, if you have some thoughts, what you like to get updated, etc. Don't hesitate to comment this in the PRs. The only real benefit for both the originator and the contributor of open source code is to learn from eachother in a dialogue.
Don't be afraid to close a PR with a short remark about the reason. Contibutors can't guess why their PRs are left alone, but they might lose interest after some time not seeing progress while they don't know what's wrong in particular. I also absolutely don't mind if you close out a PR as soon as you consider the relevant part of it is already covered (like #13). The only thing that counts is that the issue is fixed. While closing it, say it loud if you'd rather I (still) move something into one or more separate PRs.

I absolutely agree with you that it should be avoided to solve multiple issues or features in one PR and I apologize for not strictly following this rule in the past.

FWIW I'm wondering why you assume the number of commits in a PR could blow up the history? Are they not always consolidated if the PR is merged? The commits do actually help you to easier review the code. A contributor could force-push subsequent updates to avoid this. The big disadvantage of doing this is that previously reviewed code is not recognizable anymore and earlier review comments are lost.

BR Steffen

[prechelt]

Stian, I mostly made my changes in order to make cmdtab suitable for my personal use case at all.
I had not used C since 29 years and had never before used the Win32 API, so I had enough to wrap my head around even without attempting to split my contributions into multiple, independent PRs. Sorry for making your life harder that way.

My PR has relatively many commits, but they have careful commit messages and I hope the contribution of each is easy to understand that way.
Cherrypicking should work for at least some of them, I think.

With respect to coding style and quality, my personal experience is that you absolutely have to develop a notion of "good enough". Very rarely will a contribution be exactly to your liking, yet rewriting everything is too much pain in the ass. But you can get used to accepting things that are sort-of-good if you decide you want to get used to it. I strongly recommend doing that; you can adjust your acceptance level a bit up or down (and left or right) over time.

To me as well, it is more important that the functionality of my contribution arrives in the product than that I get acknowledged in any particular way.

[prechelt]

@stianhoiland
One more: In my experience, if you get something that is 63% OK, it is often far simpler to accept it and work forwards to eliminate the deficiencies than trying to explain the problems to the author in several rounds. I am so much quicker in understanding myself than in making myself understood to somebody else...

Sure, this leads to a longer commit history. But git's motto is "commits are cheap" and that is true not only technically, but in terms of content as well.