Establish firm policies for this repository

[devyte]

There are currently 1000+ opened issues and counting. If there is to be any hope of getting this repository back under control, a firm and strict policy for issues is needed. Let's discuss that here, and based on conclusions develop a write up.
Once the policy is defined, opened issues that don't comply will be closed.

As a starting point (this is, of course, open for discussion):

• Questions of type "How do I..." or "Can you please help me with..." or "Can the ESP do..." won't be handled here. Such questions should be directed at a discussion forum, like esp8266.com or stackoverflow. All issues of this type will be closed with a simple reference to the policy. (example: how do I connect to wifi)
• In a similar manner as before, issues that are obviously user error, programming language errors, lack of knowledge/experience with the use semantics of the core libs, or similar, will be closed with a reference to the policy (example: my sketch crashes. There's an char[] in it that is not null terminated. exmple: trying to use yield/delay, or libs that use yield/delay, from inside async callbacks.)
• Issues about topics already handled in the documentation will be closed in a similar manner (example: can't flash with error espcomm failed)
• Issues must be provided with a minimalist sketch. Issues with an incomplete sketch, or a huge sketch, will be closed. Maximum effort must be put forth by the person opening the issue to reduce the relevant code that reproduces the issue, so that investigation can be taken up.
• Issues with accompanied investigation that shows the root of the problem should be given priority
• Feature requests that are accompanied by a PR should undergo peer review. IF the request is accepted, the PR should then be updated based on feedback, then merged.
• Feature requests that are not accompanied by a PR:
  • could be closed immediately (not accepted)
  • could be closed after some predetermined period of time (left as candidate for somebody to pick up)
  • could be accumulated in a feature request list
    Such feature requests should in general not be targeted for a deadline or release.

I would like to know who are the developers that are still active. I would also like to know of any potential developers who are interested in contributing. How can we get more people involved?

Questions that come to mind:

1. What is the current policy for maintaining compatibility with Arduino? Example: any lib contributed, do we case if it's specific to the ESP8266 and is not compatible with other boards?
2. How should IDE-specific issues be handled?
3. How should other build systems be handled, if at all? (PlatformIO, command line make system, etc)
4. How should releases be handled? Do we want releases at regular intervals, or do we want specific milestones to be reached?
5. How should new espressif SDK features/fixes be handled? Do we want to migrate asap?
6. Is there a policy for locking issues after closed? Should there be?

@igrr thoughts? Who else should be brought into this discusion?

[igrr]

Thanks for starting this discussion @devyte, it is indeed important to have some rules formalized.

The points 1-5 (about issue handling) look very reasonable.
I would like to propose some specifics about issue triaging:

1. All contributors of this project can participate in triaging process.
2. A contributor should close the issue if it is invalid (points 1-4 in the list above).
3. Valid issues should be labeled with one (or more) of component: xxx labels.
4. If fixing the issue requires very specialized knowledge (e.g. HTTP parser, TLS, SDK integration), relevant contributor(s) should be /cc'ed. As it is common to prioritize Github notifications which contain mentions, this can help grab attention of the right person. If in doubt who to mention, open the library or source file related to the issue and see the commit log.
5. If the issue is severe, it is should be assigned to the current milestone (i.e. the next version to be released). Otherwise, it should be assigned to the next milestone. It is also okay to move issues between milestones later, depending on resources available, issue reporter feedback and such.
6. The issue can be considered severe if it affects some function for many users, or if it completely breaks certain reasonable use case for some users. At the same time, common sense should be applied: some issues reflect limitations of the chip/platform, and can not be easily dealt with, even if they affect large number of users. Marking such issues as severe is pointless.

Regarding PRs, i would also like to limit features/changes which address some very specific use case, at the expense of increased code complexity. In most cases, new features are implemented in two cases:

1. While working on a project which needs certain feature, one extends the core or the libraries to achieve the project goal.
2. A feature is requested in an the open issue, and one finds it interesting enough to work on, without having a specific project in mind.

Care should be taken not to overestimate the importance of the features added in case 1. Contributors should check if the particular feature they plan to add has previously been requested on the issue tracker. If not, please open an issue first, to discuss whether such feature is desirable/should be added.
In most cases, new libraries should be maintained in separate repositories, and added into Arduino Library Manager.

A separate case is the PRs which add support for new boards. Addition of boards which are not widely used is not encouraged. However, it can be argued that the board first needs to be listed here to achieve wide adoption (not sure if this is true). I think the way forward on this would be to have auto-generation of boards.txt for some less-verbose format, which would be easier to maintain. With that, we could also have json packages for "all boards" and "most popular" boards. I welcome others to weigh in on this topic.

Finally, regarding releases: ideally we should have a stable release cadence. Currently we have accumulated a large number of regressions which prevent the new version from being released. The goal, obviously, is to test every change thoroughly and not let massive regressions happen. Due to the fact that currently tests only cover a small portion of the overall functionality, only manual testing is possible, but even that does not work well because there is no definitive list of things to be checked. A dedicated effort on improving test coverage is needed. Also we need to make it easier for contributors to run the existing test cases to make sure that their PRs do not cause regressions.

Some thoughts on other questions:

What is the current policy for maintaining compatibility with Arduino?

We should aim to be compatible with Arduino boards (AVR/SAM) where possible. That means, new core APIs specific to the ESP8266 should be introduced with great care. APIs of common libraries (such as Wire, SPI, Servo, etc.) should be kept compatible with Arduino boards. It is okay to have extended APIs specific to the ESP8266 if that is required to fully utilize certain peripherals. But these functions should clearly be marked as non-standard.

How should IDE-specific issues be handled?

Normally, ask the issue reporter to submit the issue in arduino/Arduino project.

How should other build systems be handled, if at all? (PlatformIO, command line make system, etc)

When making changes which are likely to affect platformio or make, notify relevant people and check with them whether some corresponding changes are needed on the build system side. When a issue related to one of these build systems is reported, redirect the issue reporter to the respective issue tracker.

How should new espressif SDK features/fixes be handled? Do we want to migrate asap?

Usually it depends on the update and its scope. I have seem some which are easy to integrate and some which need more substantial changes. So it is hard to propose a rule on this. I think we can decide on a case by case basis. Usually when SDK update comes out, someone opens a issue/request to update the SDK to the latest version. Such issue can be used for discussion of the update.

Is there a policy for locking issues after closed? Should there be?

We had so far only two cases when issues had to be locked to reduce noise, so i can't propose any rule for this. Suggest deciding on a case by case basis for now.

[devyte]

Thanks @igrr. Some further questions/comments:

• Issues and features that come in can be valid, and yet could potentially still sit open for a long time without progress. In fact, we have many issues like that already. Should there be some timeout? Should bugs and feature requests be handled in the same way here?
  My instinct here for the short term is to timeout, in order to reduce the scope of pending taks.
  As an alternative, we could create a tag, e.g.: Old, Cold, whatever, to denote issues that are open, but haven't seen progress after some specific time perior.
• Some bugs or feature requests may be needed, but we may be unable to do them in the short/medium term for whatever reason. For example: the ARP bug in the SDK is a Known Issue that we can't fix. Such cases should be tagged with e.g.: Deferred, Known, whatever, and not closed.

it can be argued that the board first needs to be listed here to achieve wide adoption

I wouldn't think so. I think it is unlikely that somebody would check the ESP8266 boards manager to see if a board is listed, before making a decision on which board to try out, especially considering that it is possible to configure a generic board with most of the options from the menu. I could be wrong of course, but in my personal case, the decision of which board to adopt had to do with the hardware itself and with the board price. I tried 3 different ones, and chose from those.
Given that, I tend to agree with you: requests for oddball boards that nobody has ever heard of should be discouraged.
However, if somebody proposes a PR with an odd board addition, should we accept it or turn it away?
Here is a thought: rather than have "all boards" and "most popular", how about "Supported" and "3rd party", or along those lines? The point is to mark a difference for which ones we can maintain, and which ones the user should could have trouble with (in which case, don't open an issue here).

Currently we have accumulated a large number of regressions

I completely forgot about regressions and testcases. In fact, I don't even have any idea how to run them myself...
In that case, should new features be required to be accompanied by testcases? Exactly how much should be covered by tests in a feature is... well, a touchy topic :) However, I would think that a new feature should have at least some sanity checks, so that we can know that it worked at some point, as well as be able to search for changing behavior based on submits.
What about bugs? Should it be all/most PRs that are accompanied by tests?

[igrr]

My instinct here for the short term is to timeout, in order to reduce the scope of pending taks.
As an alternative, we could create a tag, e.g.: Old, Cold, whatever, to denote issues that are open, but haven't seen progress after some specific time period.

So far my approach was to keep these tasks (bugs/features) not assigned to any milestone. The "scope" of tasks then can be limited, if desired: just filter the list of tasks based on the milestone and/or components. Such choice has also probably played its role in the growth of the total number of open issues. On the other hand, i don't see a specific problem with the total number of issues, if all of them are categorized somehow.

I do agree that making this explicit (i.e. marking a bug/feature as "not something that will be worked on in the short term") is better in terms of communication.

Here is a thought: rather than have "all boards" and "most popular", how about "Supported" and "3rd party", or along those lines? The point is to mark a difference for which ones we can maintain, and which ones the user should could have trouble with (in which case, don't open an issue here).

Given that all possible configurations of a "generic" board should be supported, and that all other boards are some variations upon "generic" board (plus maybe custom pin definitions), i don't think there is a particular problem supporting odd boards. The problem really comes from the total number of boards: this makes changes to boards.txt which affect all boards harder to check. We can probably adopt basic requirements for newly added boards: 1) has a product page, 2) doc/boards.rst is updated with basic information about the board, 3) there is no other board choice which is functionally equivalent (same pin definitions and flash size/mode). Then we can work on moving board definitions out of boards.txt into some easier-to-maintain format which would have less redundancy (@davisonja has expressed interest in working on this at some point).

Exactly how much should be covered by tests in a feature is... well, a touchy topic :)

Indeed. I don't want to prevent people from fixing things just because there is no straightforward way to set up the test environment for certain libraries (HTTP client/server, mDNS, etc). On the other hand, new features should have at least some way of testing, even if it is just an example sketch. That could probably be part of a PR template: specifying how the proposed feature should be tested. Documenting the existing test environment would also help, i think.

[davisonja]

I've also got some thoughts :)

I think we should be collating feature requests into some sort of backlog list which, like issues, are kept until they are either implemented or made obsolete by some other change. I like the current practice of leaving them 'milestoneless'. It's a clear sign that, while interesting, they're not currently being worked on by anyone.

I also agree that both issues and feature requests need some form of evaluation. There's a balance to be struck between flexibility and complexity and its probably not helpful to attempt to include everything. On the basis that an open issue has been deemed worthy I would again suggest they be kept around - I don't think that the age of an issue necessarily means it is more or less worthy.

Compatibility should be very high on the list of important factors. Compatibility with Arduino and with existing behaviour. A nice way of demonstrating compatibility is with a comprehensive test suite. Issues of setting up the test environment aside, it would be nice to see (and prioritise) PRs with associated tests (which ideally should also reduce the amount of review required); next best would be an example sketch (which also demonstrates the intended use); and in all cases appropriate updates to relevant docs.

As a counterpoint to the question about board inclusion, one of the things I did was check what was supported. The ultimate decision was driven by appropriate hardware, but board support was certainly a factor. It does need to be easier to add boards, partly because it's not clear (and I couldn't find much documentation on the actual spec of the boards.txt!) and partly because we need to automate the generation of some files, including the linker files.
I can imagine the boards list getting unwieldy in the IDE, however, so some kind of classification, or way of turning some boards off might be useful (and/or having a boards.local.txt to allow customising the list outside of the main package) which a script would also simplify.
I have some of such a script done, but not finalised, as the Real World got in the way.

Finally, for me, at this stage, the question of build systems. With Arduino in the title I think we should be ensuring that whatever else, the Arduino IDE has full support and functionality. Having someone on hand that uses other build systems will make ensuring proper support for them much simpler (as I recall @igrr doesn't use the IDE, but uses make?) as they will have a vested interest in making it work for them. However I would expect the majority of 'new' users to be coming in with the IDE.

[devyte]

the age of an issue

The problem with accepting issues and leaving them sitting is that it leaves the scope of what is to be done open-ended, i.e.: issues keep accumulating.
All projects have Scope, Schedule and Resources.
If you increase Scope, you have to extend Schedule, or increase Resources, or both, and we can't do either.
We have very limited resources, and we want to maintain some sort of regular schedule for releases. Therefore, our only option is to reduce scope to comply with that.

So how do we reduce scope?
I'm currently doing a once-over to close issues that aren't issues for the core. That is only a first step, though.
If an issue is opened, and nobody picks it up, does it make sense to have it sitting there for a few months or years? In other words, is it ok to keep issues that we know are unlikely to get done?
I would think not.
It is this reason why my instint points at putting a timeout on issues. If nobody picks it up after some predefined time, deny the issue and close it.
Having said that, I'm rather new as a collaborator, so I won't push for this, and I'll defer to @igrr et al.

boards list getting unwieldy

Currently, there is just a list of board names displayed, which I can see getting longer and longer over time.
New boards, and new board variations of existing boards, keep popping up. I just saw a Wemos D1 Pro with 32MB flash, and shortly before that an ESP8285 with pins 9 and 10 broken out and connected to buttons. Pins 9 and 10 don't seem to be currently supported with interrupts, and they're not currently set up as INPUTs on pin init during startup!
I think we need to come up with a better approach for supporting boards.
Example (off the top of my head): families
ESP12 family => wemos D1 mini, pro, nodemcu, wittycloud, etc
ESP01 family => ESP01 original, ESP01S, 8285, etc
And in addition, expand the current Generic section to include all possible configurations. That way, if somebody has some odd new board, they can be directed to create their own configuration. If the board becomes popular, take that configuration and package it as a new board.
By expansion I mean supported pins, size of flash, size of spiffs, built-in LED, etc as parameters, or something along those lines.

I have some of such a script done

How about having a discussion about it? If that is discussed now, you could get feedback on corrections to make before finalizing.

[suculent]

One answer for all: let's vote who is watching. I'd like to help but i'm not hc low level coder like @igrr who is this platform. If you want to prioritize, start from scratch. Is there like 10 of us? Odesláno z iPhonu 6. 9. 2017 v 21:08, Develo <notifications@github.com>:

…

the age of an issue The problem with accepting issues and leaving them sitting is that it leaves the scope of what is to be done open-ended, i.e.: issues keep accumulating. All projects have Scope, Schedule and Resources. If you increase Scope, you have to extend Schedule, or increase Resources, or both, and we can't do either. We have very limited resources, and we want to maintain some sort of regular schedule for releases. Therefore, our only option is to reduce scope to comply with that. So how do we reduce scope? I'm currently doing a once-over to close issues that aren't issues for the core. That is only a first step, though. If an issue is opened, and nobody picks it up, does it make sense to have it sitting there for a few months or years? In other words, is it ok to keep issues that we know are unlikely to get done? I would think not. It is this reason why my instint points at putting a timeout on issues. If nobody picks it up after some predefined time, deny the issue and close it. Having said that, I'm rather new as a collaborator, so I won't push for this, and I'll defer to @igrr et al. boards list getting unwieldy Currently, there is just a list of board names displayed, which I can see getting longer and longer over time. New boards, and new board variations of existing boards, keep popping up. I just saw a Wemos D1 Pro with 32MB flash, and shortly before that an ESP8285 with pins 9 and 10 broken out and connected to buttons. Pins 9 and 10 don't seem to be currently supported with interrupts, and they're not currently set up as INPUTs on pin init during startup! I think we need to come up with a better approach for supporting boards. Example (off the top of my head): families ESP12 family => wemos D1 mini, pro, nodemcu, wittycloud, etc ESP01 family => ESP01 original, ESP01S, 8285, etc And in addition, expand the current Generic section to include all possible configurations. That way, if somebody has some odd new board, they can be directed to create their own configuration. If the board becomes popular, take that configuration and package it as a new board. By expansion I mean supported pins, size of flash, size of spiffs, built-in LED, etc as parameters, or something along those lines. I have some of such a script done How about having a discussion about it? If that is discussed now, you could get feedback on corrections to make before finalizing. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub, or mute the thread.

[herrold]

@devyte mentioned:

It is this reason why my instinct points at putting a timeout on issues. If nobody picks it up after some predefined time, deny the issue and close it.

And I would say I am quite against this. Doing it 'mechanically' by programmatic application of an aging rule is the approach in the fedoraproject.org Linux process, and it ends up while doing research into something that the same issue gets filed, and closed, and re-filed, and re-closed, and re-re-filed, but never worked on. I speak, having used that bug tracker for something over fifteen years (pre-dating Fedora, when I was a private 'testers-list' member for Red Hat on their prior RHL offerings from the earliest days, and then forking off to start the CentOS project with a couple other developers

Better perhaps is to 'triage' all bugs, tag is with a 're-check in N days' notation, and ask the reporter:

are you still interested in this and can you still reproduce the error? If not in either case, you may simply ignore this email and we will auto-close the bug in N days

where N is something like 30 days, and not so short as seven because that is too fast for the 'social voluntary' model of an Open Source community

The other thing we do in the Linux Standards Base is to have a weekly 'triaging' session to categorize the incoming load, and to

1. close at once as inapplicable,
2. mark as 'nice to have but not a priority; patches welcome, or
3. tag it to a release target in the road-map

Then as an addition, writing, and maintaining a FAQ, in WIKI form. This worked well for us at CentOS, so that a repeated question could be pointed at a FAQ target, and closed at once. I know the wiki we used there permitted an editor to subscribe to ALL new posts and ALL edits, and also to add ACLs to avoid wiki-spam, and that is important. More importantly as the body of the WIKI FAQ grows, the web-crawlers will notice and a virtuous circle of good content becoming great will result, as people 'weed and fertilize' in that garden

-- Russ herrold

[vicnevicne]

If I may:

the age of an issue

If you increase Scope, you have to extend Schedule, or increase Resources, or both, and we can't do either. We have very limited resources, and we want to maintain some sort of regular schedule for releases.

I also beg to disagree. In my view, it is important to be able to distinguish issues that are invalid or fixed on one side, and issues that are acknowledged as actual problems in the core on the other side, even though there is no resource to work on them at a given time.
Some users could encounter the same issue at a later time and be reassured that the problem is not with their code. Some might be interested in getting involved and helping fix it. Or maybe some could propose or benefit from a proposed workaround.

Unless I'm mistaken, Github is rather poor regarding issue classification. Bugzilla for example has an intermediate "resolved" state and an issue can be resolved and marked as "LATER".
As we don't have that possibility here, I think the closest we can do is keep these issues open with no milestone (or even with a generic milestone called "Future").

At any given time, the "Scope" is clear: it is the next milestone.

That being said, @devyte, you've been doing an impressive triaging job lately. Much appreciated!

[davisonja]

the age of an issue

The problem with accepting issues and leaving them sitting is that it leaves the scope of what is to be done open-ended, i.e.: issues keep accumulating.
All projects have Scope, Schedule and Resources.
If you increase Scope, you have to extend Schedule, or increase Resources, or both, and we can't do either.
We have very limited resources, and we want to maintain some sort of regular schedule for releases. Therefore, our only option is to reduce scope to comply with that.

I don't think quite the same concept of fixed resourcing applies here, and we have some control over the schedule in terms of what is included in each milestone - there's no great harm, I believe, in having some issues that are not currently attached to a milestone. They represent the backlog of things that we'd like done at some point (I'm assuming that priority is given in some form so that the backlog is full of things that are either low priority or currently lacking a developer).
Would, for example, #905 be discarded? It was created in 2015, remained dormant for about a year and then had a small flurry of activity, but went dormant again Jan 2017. I have a solution for that issue, but to simplify life it really needs this script to generate linker scripts and boards.txt files. Presumably prior to Dec 2016 there was no resource to address it, then I discovered this fun new world and joined in (as time has permitted!). My overall point being that in an open source environment such as this Resourcing, particularly developer resources, while limited at any given time, are quite changeable. Either due to expertise, or desire, relevant issues may remain inactive for a while, but still be implemented. Closing such issues makes them much harder to find.
I favour the approach of leaving issues that have been deemed worthy (and not all will be) milestoneless as a record for future contributors. Management of resourcing as it applies to a schedule is achieved by assigning tickets to a milestone.

boards list getting unwieldy

Currently, there is just a list of board names displayed, which I can see getting longer and longer over time.
New boards, and new board variations of existing boards, keep popping up. I just saw a Wemos D1 Pro with 32MB flash, and shortly before that an ESP8285 with pins 9 and 10 broken out and connected to buttons. Pins 9 and 10 don't seem to be currently supported with interrupts, and they're not currently set up as INPUTs on pin init during startup!
I think we need to come up with a better approach for supporting boards.

Exactly. Families might be an interesting approach.
A quick scan of the boards.txt file will likely show you that there are large overlaps between the various boards. In creating a script it seemed preferable (especially as my work on it was delayed!) to be able to run it over an existing boards.txt to initialise the data. One of the things that does is to collate all the board settings that are the same - so the data has the concept of a 'config line' and the boards to which it applies. The idea being to have a 'generic' set of board settings, and to specify only the changes required for other boards, extending this through families could see a generic base, with a family overlay and then board changes.
However, you are right, this should probably be broken out into it's own issue for a discussion, rather than hijacking this or #905! I hadn't started the discussion yet as I wanted to have a look at how the various boards related to each other, and whether some kind of hierarchical definition was warranted, or not. There does seem to be a lot of overlap.
I created a new issue #3582

I'd also like to echo @vicnevicne in saying thanks for your efforts across the board @devyte!

[devyte]

@herrold what you said is fully compatible with what I meant. I did not imply closing issues in an automated way or anything like that, but rather that it's just pointless to have open issues sitting in the tracker forever. If an issue has been open for a while (30 days or whatever), there is no feedback, or nobody is willing to pick it up, then close it.

@vicnevicne said:

At any given time, the "Scope" is clear: it is the next milestone.

You are referring to the scope of a release. In that sense, you are correct: assignments can be made to define the scope for a particular release. However, I'm referring to the scope of the repo, or rather, the project as a whole. Right now, I've been working on cleanup for about one week. At the rate I'm going, assuming I can keep the rate up, which is unlikely, it will take me over one month just to go through the open issues and clean them up. Give that some thought: the repo is in a state where it takes over one month just to read through the open issues. If the current state of the repo continues, the open issues will continue to pile up until it takes even more time just to go through them. That means that it is impossible to go through all open issues to set milestones for a release, and must instead settle for picking and choosing at random, usually from the more recent ones. Which means in turn that the older issues just sit there, because it is very unlikely that developers will look at it again.
And that situation just gets worse and worse as time goes by and issues pile up.

@davisonja
About the eboot issue, I'm not speaking in absolute terms. Such an issue, where the ESP could soft-brick, I would consider critical. I would propose to handle them in some special manner, i.e.: long-term.
In contrast, consider a request to port an Arduino library, or worse: a 3rd party lib in some external repo, that currently doesn't work with the ESP. Only one user wants it. the issue sits there for 2 years without feedback. Does it makes sense to keep it open?

Closing such issues makes them much harder to find.

Not really, the issues are still there after closing, still show up in google, and still show up in the repo searcher after removing is:open, which is trivial to do. I do this regularly, and I'm sure I'm not the only one.

leaving issues that have been deemed worthy (and not all will be) milestoneless

This is fine, as long as new issues go through some filtering process, which is exactly what this discussion is about.

Everyone, I am not saying we should deny everything, or even deny most issues. What I am saying is that we need some filtering process to figure out which issues we want to keep as open, and which issues we are going to deny, and that this filter needs to be such that the number of issues resolved must be greater than the number of issues coming in. If we don't meet that simple rule, this repo will eventually blow up.
We can put a triaging procedure or guideline in place, we can assign milestones and keep a schedule, or we can do whatever we agree to do, but in order to do it, we must be in control of the overall scope. Even after I'm done with the cleanup, I estimate there will be about 600+ issues left open. That is still far too much. The resources available are very few. Consider the number of PR's that have been sitting there for months. That is a clear indication of too few resources: users have submitted potential contributions, and we can't even get to reviewing them.

Ivan can't do everything himself. I personally care about the little ESP and this repo, I have been following it for a long time. I haven't opened a single issue or asked a single question during my development, but rather resolved my problems myself, and I have done this to not add to the load that I am observing.
It is for this reason that I decided to step up and spend a considerable amount of my personal time to do cleanup instead of development.
We can define the specifics of the methodology, but please help me direct this repo into a managable state. If we start by agreeing that the number of open issues must be reduced to something managable, then there is a chance to achieve that.

[davisonja]

I don't seem to have been quite clear, sorry - I'm in agreement with you on almost everything :)

We can define the specifics of the methodology, but please help me direct this repo into a managable state. If we start by agreeing that the number of open issues must be reduced to something managable, then there is a chance to achieve that.

I agree 100%.
There are too many open issues, and there's a long history of people using the issue tracker as a forum.
I think there are definitely issues where a timeout is not appropriate, but you're right in that there are others for which it is probably essential. Perhaps we have a timeout that suitable issues can be exempt from?

I do realise you can remove is:open (I also do so), on further reflection I think my concerns are probably addressed by ensuring such things are suitably labelled. I think it is important for newcomers to be able to find things that have been requested, but haven't met the threshhold for action by the current developer base: appropriate labelling and some docs saying such would resolve that.

The current state of the tracker is quite unwieldy and I am very thankful that you have opted to devote (what will be a huge amount of) time to sorting it all out, and am keen to help with the process, cleanup and development.

[devyte]

@igrr is there anyone else that you think should be brought into this this? If not, I'll (slowly) start working on a condesated version of what has been discussed.

[igrr]

I think there are definitely issues where a timeout is not appropriate, but you're right in that there are others for which it is probably essential. Perhaps we have a timeout that suitable issues can be exempt from?

That sounds very reasonable. I would suggest that we have some label to indicate that an improvement / bug needs to be handled at some point, but no one has committed to working on it. E.g. "backlog". Improvement requests which have not been placed on the backlog by one of the contributors (irrelevant or "pie-in-the-sky" ones) can be closed after, say, a month.

[Makuna]

Btw, please feal free to bring me in on issues where I contributed code. While my time is not as open to allow much new contributions, I can continue to support work I have done.

Also, don't forget the Gitter channel, need to point some of those question issues to it and set expectations of what are real issues.

Something I have ran into with my own libraries, is that common questions are asked alot, and having a wiki or at least a FAQ helps reduce the issues being generated.

[devyte]

Sorry for sort of dropping off the map, I've been dealing with some personal issues, including the loss of someone close. It's been a... trying couple of weeks.
I've tried to hold off the incoming new issues as I could, but I lost some ground anyways. I expect to continue the clean up effort again this week.
In the meantime, I put together a condensed version of this discussion as a first draft under PR #3655 .
To be clear, the document describes policy rules to apply, and doesn't describe the actual triaging process, which is something different. If we want to formalize a triaging process, we can do that as well in a separate document or diagram.
Anyways, please review.

[per1234]

You might consider adding a CONTRIBUTING.md file (see: https://github.com/blog/1184-contributing-guidelines). This will cause a message:

Before you open an issue please review the contributing guidelines for this repository.

to be displayed when someone starts to open a new issue, and a similar message is displayed when submitting a PR.

I realize guidelines are already documented in README.md but this will make it more likely they will be seen. You could link to CONTRIBUTING.md from README.md to avoid duplicate content.

If you want to further increase the visibility of CONTRIBUTING.md you can add an issue template file (ISSUE_TEMPLATE.md) that adds a reminder to the text input field of the new issue page. I think this will be much more difficult to ignore than GitHub's CONTRIBUTING.md message. You can see an example of how this could be implemented here:
arduino/Arduino#6681

I know this is more a discussion of administration but I think a little effort to educate users on contributing guidelines will pay off many times over in reducing the administrative workload by preventing invalid issue reports and increasing the quality of the issues/PRs that are submitted. Recruit the user to do the preliminary triage.

If either is of interest I'm happy to submit a PR for them.

[devyte]

The cleanup effort is mostly done, at least the first pass. It left 500+ issues open, and now afternthe 2.4.0 release effort that dropped further to 400+ open issues. Ideally we should be at ~100 issues, but now the repo is manageable. The POLICY doc is merged, and is serving its purpose.
There is still more cleanup work to do, such as continue closing old issues that don't really merit pursuing, where requested feedback was not given, etc, but I'll be handling that weekly or so.
At this point, the only pending is to add a CONTRIBUTING doc that links to/mentions the POLICY.

[vicnevicne]

I really think the Issue Template should be modified to start with something like

If you need help with your project, please direct your request to a forum such as esp8266.com or stackoverflow. Only if it appears the issue is due to a bug in the ESP8266 Arduino core (this project) should you open an issue here by filling up the form below (we mean it). For more info, please read https://github.com/esp8266/Arduino/blob/master/POLICY.md

Hopefully people (including us) would not waste time on issues like #4313
What do you think ?

[devyte]

@vicnevicne I agree, and I've been thinking along similar lines for a while now. To be honest, I don't understand why users don't even bother reading the issue template, and many even delete it in its entirety.

[devyte]

In addition to CONTRIBUTING, SUPPORT should also be added. Thanks for the suggestion @Makuna .