6 ms·

Some practical rules I wish projects would follow, from personal experience: * Have a README. At the top of the README, say what the project does. Document how

Some practical rules I wish projects would follow, from personal experience: * Have a README. At the top of the README, say what the project does. Document how to build and run it. * Make sure every artifact of the project is buildable from source. This includes project websites and binary releases. Document this process. * Have a clear assignment of responsibilities, and respect it. If you let someone take over a task, don't micromanage them. * Document your availability. If you have to step away from the project, put this at the top of the README, even if it's temporary. Don't drip-feed interaction - be either on or off. * Be responsive to issues and pull requests. That doesn't mean accept everything, but answer quickly, even if just to say you need more time to look into it. Don't leave stale reviews open. * Don't close bug reports just because they're old. A bug report is either good or bad - that is, the bug is either reproducible or it isn't. A bad bug report is bad from the start; close it quickly - or else, don't close it just because enough time has passed. (This goes doubly for bug reports with advice.) * On documentation: one example is worth a dozen descriptions. Check if your language offers you a way to combine documentation and unittests; this is of high worth - take full advantage. * Have a style guide. Link it in the README. This saves you time in review. * Set up CI. Nowadays, there's plenty of free services that integrate with Github, so there's really no reason not to. (Combo bonus: CI with style check!)

JD557 7y ago
> * Have a style guide. Link it in the README. This saves you time in review. I would go even further and recommend using some automatic style formatter. That way, you can fail the CI step if the code is not correctly formatted and that problem is trivial to fix (just run the formatter).
- FeepingCreature 7y ago
  Oh yeah, good point.
- saagarjha 7y ago
  Plus I find that having an impersonal tool tell people that they did something "wrong" makes them a lot more likely to fix it and still be amenable to your future suggestions.
scrollaway 7y ago
> Don't close bug reports just because they're old. A bug report is either good or bad - that is, the bug is either reproducible or it isn't. A bad bug report is bad from the start; close it quickly - or else, don't close it just because enough time has passed. And don't lock them as stale once closed. Holy shit, it's infuriating seeing projects abuse what is essentially an anti-harrasment tool to prevent people from pinging old issues with relevant information. Especially if said old issue is a top hit on Google for some set of keywords. Losing the context of the old issue often kills contributions outright.
- dessant 7y ago
  You can learn about a maintainer's experience with closed issues that keep being bumped here: https://www.henryzoo.com/an-issue-with-issues/ https://www.henryzoo.com/an-issue-with-issues/ Even though I'm maintaining Lock Threads [1], I sometimes shake my head when I come across a closed issue that was locked by it, but I also have to admit that all I want is to ask a question quickly and get the information I need, without considering how my shortcuts affect maintainers. There may be times when there's a legitimate reason for commenting on a long-resolved issue, but unfortunately most of the comments on closed issues are low effort support requests. Locking them as resolved is the best solution we have so far to avoid spending our time retriaging closed issues. [1] https://probot.github.io/apps/lock/ https://probot.github.io/apps/lock/
  - scrollaway 7y ago
    I get you. I'm a maintainer as well. But I'm not even talking about "long resolved" issues. Last week I saw an issue created by the maintainer themselves to talk about some upcoming milestone or something, that got autolocked before the milestone got there. Yes, it's just misconfiguration, but when you're configuring these tools you're never thinking about the damage the autolocks do to your project if you're not very careful with the settings. Remember, the people just get turned off from contributing. They don't stick around to give feedback on this being the root cause. Hell, I never did, and I'm very vocal about autolocking being toxic.
  - jacobolus 7y ago
dessant 7y ago
These are all sensible rules, and I think plenty of open source projects are doing fine on this front, though its important to note that properly keeping up with these practices is a full-time job.
- astrid88 7y ago
  Yeah, I have a feeling that plenty projects start with this nice set of rules and they get lost along the way...
piotrkubisa 7y ago
> Document how to build and run it. This, especially in non-web repos (C/C++) is common mistake of READMEs and docs. Let's take an example of XFCE-WM project [0]. The main README does not include any information how to compile it, nor provides any link to the documentation how to build this very specific code. If you will google it you might find following wiki page [1], which is general for all repositories. In the COMPOSITOR [2] file you might notice some information about flags that you can provide during building, and that's great such doc has been created, but except that document I couldn't find any information how "fresh contributor" would like to debug and test some change in code that he made in the cloned repository. Download and install some linux distro on virtual machine and then invest (1h+) to configure it accordingly to run it there? Use Xephyr (I guess "fresh contributor" has never heard about this tool)? In my honest experience, the "how to build" step is probably included in many of repositories, but the "how-to-run" is usually lacking in READMEs and it is what I really would like to see in complex projects (e.g. desktop environment). > Document your availability. If you have to step away from the project, put this at the top of the README, even if it's temporary. Don't drip-feed interaction - be either on or off. One more thing related to docs and "how-to-build-&-run" thing. Let's say the project owner have some critical accident that made him unavailable to push progress of development forward for few months or longer. If there isn't any knowledge shared (docs, other contributors) then I guess the project will be stalled and possibly forgotten if there is no clear incentive to use alternative methods of repo maintenance (e.g. fork). [0]: https://github.com/xfce-mirror/xfwm4 https://github.com/xfce-mirror/xfwm4 [1]: https://docs.xfce.org/xfce/building https://docs.xfce.org/xfce/building [2]: https://github.com/xfce-mirror/xfwm4/blob/master/COMPOSITOR https://github.com/xfce-mirror/xfwm4/blob/master/COMPOSITOR [3]: https://en.wikipedia.org/wiki/Xephyr https://en.wikipedia.org/wiki/Xephyr
- saagarjha 7y ago
  To be fair, that looks like a mirror that’s been separated from its “intended” location (where there might be a link to these instructions) plus it’s a traditional “./configure && make && make install” type project anyways
  - piotrkubisa 7y ago
jsight 7y ago
* Don't close bug reports just because they're old. A bug report is either good or bad - that is, the bug is either reproducible or it isn't. A bad bug report is bad from the start; close it quickly - or else, don't close it just because enough time has passed. (This goes doubly for bug reports with advice.) I disagree... lots of bug reports actually are not bad at all, but are also not something that you want to prioritize. If multiple parties look at a bug report repeatedly for years and do not prioritize it, its a pretty good sign that it is something that will not be done. Closing bugs that aren't going to be done is a good thing, but it isn't always such an obvious decision on day 1. Of course, they can always be reopened (or duplicated) if the situations change.
- FeepingCreature 7y ago
  Well, then the bug stays open. :shrug: Why is that so bad? The only reason I can see to close old bugs is that a project wants to make it seem like it has fewer issues than it does, and hopes that users won't notice the issue.
  - dspillett 7y ago
    > and hopes that users won't notice the issue It is a little more than that in many cases. People judging a project overall by the number of open bugs reports, no matter how minor, isn't really fair if there is considerable development on more important bugs/features/other elsewhere in the project.
    - beart 7y ago
      It also isn't fair for people who assume a project that has a large number of closed issues is highly active, when in fact, a large number of those issues have just never seen any activity and were closed for being stale.
      - dspillett 7y ago
        If the issues are closed with WONTFIX or similar status, as discussed nearby in this thread, then it should still be clear that something is going on. It is then up to the reader to decide if that something is enough for them to worry about or not.
beart 7y ago
When I see projects on Github using the Stale Bot to automatically close issues, I don't bother looking any further. There is something so incredibly infuriating about having an issue closed automatically - when I know it is still a problem but no one has had time to look at it yet. It reminds me very much of the MSDN community threads where the accepted answer is "reinstall Windows and see if that fixes it" with hundreds of replies after that indicate it did not help.
- ljm 7y ago
  I wonder if this would change if GitHub took the simple step of removing the PR/issue counters from the navigation. Because I can’t see a reason for automatically dismissing issues you ignore as stale, unless you think the issue count is bad optics for your project. As well as github’s issue triage piece being non-existent. All you’ve got is a list that shows you 20 things at a time, and it suffers from the social media effect where anyone can add bullshit memes to the thread once someone on twitter has directed the mob to it. You don’t really see that happen so much outside of github.
rmetzler 7y ago
The CI is something that keeps me from contributing. I don’t say it doesn’t do it’s job and I don’t say it’s not useful. What I mean is the CI is often set up to enforce rules that aren’t clear when you create the pull request. I’ve a pull request to Ansible that’s open for ~ 2 years now and I keep on doing commits just to satisfy the CI without getting any actual feedback from the Ansible maintainers whether or not my pull request will be accepted. And just yesterday I opened a pull request on the Azure cli and the CI pipeline forbids pull requests to master without telling first time contributors the accepted workflow. My contribution is just a small typo fix in a help text, but adding a sentence of how to create a good pull request in the issue template would actually go a long way.
hockeystick 7y ago
so true.
yongjik 7y ago
> Don't close bug reports just because they're old. <rant> Somebody should tell this to Kubernetes developers. Also, thanks to Github's braindead UI of marking every issue as either "Open" or "Closed", once I click a Google link to any Kubernetes issue I have no idea if (1) the issue is closed because it was fixed in the latest version (so I have to upgrade), or (2) the issue is closed because it turned out to be invalid (so I have to search for something else), or (3) the issue wasn't solved at all, but Kubernetes team decided to tell everybody "Haha we don't care. And to really drive the point home that we don't care, we're gonna auto-close it for lack of activity." So I have to scroll all the way down and read the discussion. Sorry, that was my pet peeve #168 for Kubernetes. Carry on. </rant>

JD557 7y ago

> * Have a style guide. Link it in the README. This saves you time in review. I would go even further and recommend using some automatic style formatter. That way, you can fail the CI step if the code is not correctly formatted and that problem is trivial to fix (just run the formatter).

FeepingCreature 7y ago
Oh yeah, good point.
saagarjha 7y ago
Plus I find that having an impersonal tool tell people that they did something "wrong" makes them a lot more likely to fix it and still be amenable to your future suggestions.

scrollaway 7y ago

> Don't close bug reports just because they're old. A bug report is either good or bad - that is, the bug is either reproducible or it isn't. A bad bug report is bad from the start; close it quickly - or else, don't close it just because enough time has passed. And don't lock them as stale once closed. Holy shit, it's infuriating seeing projects abuse what is essentially an anti-harrasment tool to prevent people from pinging old issues with relevant information. Especially if said old issue is a top hit on Google for some set of keywords. Losing the context of the old issue often kills contributions outright.

dessant 7y ago
You can learn about a maintainer's experience with closed issues that keep being bumped here: https://www.henryzoo.com/an-issue-with-issues/ https://www.henryzoo.com/an-issue-with-issues/ Even though I'm maintaining Lock Threads [1], I sometimes shake my head when I come across a closed issue that was locked by it, but I also have to admit that all I want is to ask a question quickly and get the information I need, without considering how my shortcuts affect maintainers. There may be times when there's a legitimate reason for commenting on a long-resolved issue, but unfortunately most of the comments on closed issues are low effort support requests. Locking them as resolved is the best solution we have so far to avoid spending our time retriaging closed issues. [1] https://probot.github.io/apps/lock/ https://probot.github.io/apps/lock/
- scrollaway 7y ago
  I get you. I'm a maintainer as well. But I'm not even talking about "long resolved" issues. Last week I saw an issue created by the maintainer themselves to talk about some upcoming milestone or something, that got autolocked before the milestone got there. Yes, it's just misconfiguration, but when you're configuring these tools you're never thinking about the damage the autolocks do to your project if you're not very careful with the settings. Remember, the people just get turned off from contributing. They don't stick around to give feedback on this being the root cause. Hell, I never did, and I'm very vocal about autolocking being toxic.
- jacobolus 7y ago

dessant 7y ago

These are all sensible rules, and I think plenty of open source projects are doing fine on this front, though its important to note that properly keeping up with these practices is a full-time job.

astrid88 7y ago
Yeah, I have a feeling that plenty projects start with this nice set of rules and they get lost along the way...

piotrkubisa 7y ago

> Document how to build and run it. This, especially in non-web repos (C/C++) is common mistake of READMEs and docs. Let's take an example of XFCE-WM project [0]. The main README does not include any information how to compile it, nor provides any link to the documentation how to build this very specific code. If you will google it you might find following wiki page [1], which is general for all repositories. In the COMPOSITOR [2] file you might notice some information about flags that you can provide during building, and that's great such doc has been created, but except that document I couldn't find any information how "fresh contributor" would like to debug and test some change in code that he made in the cloned repository. Download and install some linux distro on virtual machine and then invest (1h+) to configure it accordingly to run it there? Use Xephyr (I guess "fresh contributor" has never heard about this tool)? In my honest experience, the "how to build" step is probably included in many of repositories, but the "how-to-run" is usually lacking in READMEs and it is what I really would like to see in complex projects (e.g. desktop environment). > Document your availability. If you have to step away from the project, put this at the top of the README, even if it's temporary. Don't drip-feed interaction - be either on or off. One more thing related to docs and "how-to-build-&-run" thing. Let's say the project owner have some critical accident that made him unavailable to push progress of development forward for few months or longer. If there isn't any knowledge shared (docs, other contributors) then I guess the project will be stalled and possibly forgotten if there is no clear incentive to use alternative methods of repo maintenance (e.g. fork). [0]: https://github.com/xfce-mirror/xfwm4 https://github.com/xfce-mirror/xfwm4 [1]: https://docs.xfce.org/xfce/building https://docs.xfce.org/xfce/building [2]: https://github.com/xfce-mirror/xfwm4/blob/master/COMPOSITOR https://github.com/xfce-mirror/xfwm4/blob/master/COMPOSITOR [3]: https://en.wikipedia.org/wiki/Xephyr https://en.wikipedia.org/wiki/Xephyr

saagarjha 7y ago
To be fair, that looks like a mirror that’s been separated from its “intended” location (where there might be a link to these instructions) plus it’s a traditional “./configure && make && make install” type project anyways
- piotrkubisa 7y ago

jsight 7y ago

* Don't close bug reports just because they're old. A bug report is either good or bad - that is, the bug is either reproducible or it isn't. A bad bug report is bad from the start; close it quickly - or else, don't close it just because enough time has passed. (This goes doubly for bug reports with advice.) I disagree... lots of bug reports actually are not bad at all, but are also not something that you want to prioritize. If multiple parties look at a bug report repeatedly for years and do not prioritize it, its a pretty good sign that it is something that will not be done. Closing bugs that aren't going to be done is a good thing, but it isn't always such an obvious decision on day 1. Of course, they can always be reopened (or duplicated) if the situations change.

FeepingCreature 7y ago
Well, then the bug stays open. :shrug: Why is that so bad? The only reason I can see to close old bugs is that a project wants to make it seem like it has fewer issues than it does, and hopes that users won't notice the issue.
- dspillett 7y ago
  > and hopes that users won't notice the issue It is a little more than that in many cases. People judging a project overall by the number of open bugs reports, no matter how minor, isn't really fair if there is considerable development on more important bugs/features/other elsewhere in the project.
  - beart 7y ago
    It also isn't fair for people who assume a project that has a large number of closed issues is highly active, when in fact, a large number of those issues have just never seen any activity and were closed for being stale.
    - dspillett 7y ago
      If the issues are closed with WONTFIX or similar status, as discussed nearby in this thread, then it should still be clear that something is going on. It is then up to the reader to decide if that something is enough for them to worry about or not.

beart 7y ago

When I see projects on Github using the Stale Bot to automatically close issues, I don't bother looking any further. There is something so incredibly infuriating about having an issue closed automatically - when I know it is still a problem but no one has had time to look at it yet. It reminds me very much of the MSDN community threads where the accepted answer is "reinstall Windows and see if that fixes it" with hundreds of replies after that indicate it did not help.

ljm 7y ago
I wonder if this would change if GitHub took the simple step of removing the PR/issue counters from the navigation. Because I can’t see a reason for automatically dismissing issues you ignore as stale, unless you think the issue count is bad optics for your project. As well as github’s issue triage piece being non-existent. All you’ve got is a list that shows you 20 things at a time, and it suffers from the social media effect where anyone can add bullshit memes to the thread once someone on twitter has directed the mob to it. You don’t really see that happen so much outside of github.

rmetzler 7y ago

The CI is something that keeps me from contributing. I don’t say it doesn’t do it’s job and I don’t say it’s not useful. What I mean is the CI is often set up to enforce rules that aren’t clear when you create the pull request. I’ve a pull request to Ansible that’s open for ~ 2 years now and I keep on doing commits just to satisfy the CI without getting any actual feedback from the Ansible maintainers whether or not my pull request will be accepted. And just yesterday I opened a pull request on the Azure cli and the CI pipeline forbids pull requests to master without telling first time contributors the accepted workflow. My contribution is just a small typo fix in a help text, but adding a sentence of how to create a good pull request in the issue template would actually go a long way.

hockeystick 7y ago

so true.

yongjik 7y ago

> Don't close bug reports just because they're old. <rant> Somebody should tell this to Kubernetes developers. Also, thanks to Github's braindead UI of marking every issue as either "Open" or "Closed", once I click a Google link to any Kubernetes issue I have no idea if (1) the issue is closed because it was fixed in the latest version (so I have to upgrade), or (2) the issue is closed because it turned out to be invalid (so I have to search for something else), or (3) the issue wasn't solved at all, but Kubernetes team decided to tell everybody "Haha we don't care. And to really drive the point home that we don't care, we're gonna auto-close it for lack of activity." So I have to scroll all the way down and read the discussion. Sorry, that was my pet peeve #168 for Kubernetes. Carry on. </rant>