I find we are losing a lot of time (and also probably some contributors) by requesting people to provide good bug reports, explaining all our contribution process. So I’m wondering if it will be good to improve our contribute page. I found a nice guide where it explains all the good practices and also includes some examples for other projects.
Before moving forward, I will like to have some feedback about such initiative. If you think that this will be interesting I will like to see which points are more interesting for you. I will like to hear opinions from people how failed to contribute or feel lost in the project.
P.S: My direct messages are also open if somebody prefers to keep his opinion private.
When I contribute to a project if I have to read more than a few paragraph about the process, I just give up or just submit without reading.
So in your example link, I did not read it because it is too long.
Sincerly that is the feeling that I had after reading your mail. But I’m gona retry.
On the tryton spanish days I asked on some developers why they are not contributing more and I had two replies:
Missing time
The contribution processs is to complex so I get lost before doing everything.
We already have all the steps explained on the webpage so for me this is a sign that this is not clear enought. Also reported issues are most of the time missing some crucial information (for example some steps to reproduce) afected components. There is also a miss understanding about the usage of a the discuss forum and the issue tracker.
All this problems produce that contributors and maintainers lose time. The idea of the guides is to make it clearer so we have more contributors with the same number of maintainers.
I doubt about that. For me it is just that people does not care. I can see that former contributors do not contribute anymore and just report issues. It is just that they do not want to spend the needed time to make a good contribution.
I do not think we can fix laziness of people. We have already explained to some people many times and they still continue to make bad report. They just do not care. For me the only valid respond is to not care also.
We should just loose time on people who makes us losing time.
I do not see why someone who does not have time or care to read the current guide lines will read a bigger one.
So we can improve the current guide line if some parts are ambiguous etc. But we must keep it simple and small.
Sincerly, I doubt people will find time to make good contribution if we do not explain them what a good contribution is it and what we expect for them. For example:
We expect people to run tests but we do not explain how to do so.
We ask people to include the repository name but we do not explain how the project is estructured.
We ask for people to write maningfull commit messages, but we do not include any explanation on the how to develop page.
We ask to include all pool methods, but we do not include any example (so people do not understand).
We ask for double quotes for “natural language” but we do not explain what natural language is and do not provide any example.
I have the fear that it won’t be possible to have a small guide explaining everything (because tryton is a complex system).
I’m curious, why you prefer to keep it small? I will prefer to have a more verborse documentation to ensure everything is clear for the reader.
That’s why github is so popular (that and above all the network effect of course): the contribution workflow is the same for 99% of the project hosted there namely (a) fork and create a PR, (b) ensure the CI is green.
But it’s not a contribution guarantee, I stumbled upon this issue in python: Issue 28607: C implementation of parts of copy.deepcopy - Python tracker which has a patch but was never turned into a PR (and I suspect there are dozens like that where the author never bothered to make a PR after python started using github).
So yes, in the end it’s the contributor which decide to allocate its time and if he perceive that the process is too complex / cumbersome then he stops.
Of course I don’t find it much more difficult than contributing through github but I am not the one who should understand it .
But my bet is that even if we had the github contribution workflow we would end up having people not contributing has much as they could.
Why is that?
I see some factors:
Tryton is a small project about a niche usecase (it’s easier to find people wanting to contribute to an HTML templating engine than to an ERP)
The quality enforced for the contribution is quite high thus the review process might take a long time which results in people stopping the process or people doing it once (or twice) but never again
There are some grey areas sometimes but usually it’s not that bad.
Totally agree but when people comes to the project they do not know this fact (we never explain that on the contributor guidelines). For me it will be also good to explain that the review process may take a while (and even how to ping us if we miss to review some work) to make it clear there is no issue from their side and they can continue helping on other topics.
Indeed but I would prefer to have automated test than having to explain how to run test.
Indeed instead of explaining I would prefer it was automated.
Good luck to define a “good” commit message.
This is not part of the contribution but the style guide. If someone is contributing to the point it has to follow the style guide, he should know what is “Pool”.
We can put a link to the wikipedia page. But I doubt we have to define (probably badly) every common words.
Maintenance. It is worse to have bad documentation than missing documentation.
But also it will take a huge effort to have every details completely explained right without any loophole.
And also I do want flexibility over strict rules because I already contribute too much to bureaucratic projects to know the pain.
Anyway I do not think there is much to discuss here. As usual if someone want to improve something he just have to make incremental proposal.
I have a modified version of upload.py script which sets the prefix based on the folder name (which is the repository name). How can I upload it to our codereview server?
Automatic testing will not replace manual one. Contributors should be able to run the tests locally to ensure that everything is working before uploading a patch.
I see you already add the link. But probably I will prefer to explain it because the wikipedia link is hard to understand. I always use: “Strings that should be read by an human” vs ‘Strings that should be read by a computer’ which is normally easier to understand.
I share make code if that helps somebody. updated the line 2664 to be like this:
if title and not options.issue:
message = message or title
# Include repository name as prefix
title = '%s: %s' % (os.path.basename(os.getcwd()), title)
.