Suggestions of how to make nodemcu project organized! call for help. #577
Comments
|
Hello, I've been working on that recently on my project clixx.io Basically what I do is put every project into a directory off ~/IoT. Sorry One of the big problems with Arduino is they don't give you a management I'm busy writing, and testing the documentation. But I'm just showing a few On Mon, Jul 27, 2015 at 1:20 AM, zeroday [email protected] wrote:
|
|
probably this is a better shot of the web interface: On Mon, Jul 27, 2015 at 1:25 AM, David Lyon <[email protected]
|
|
dir? web interface? |
|
Every ESP8266 project goes into a project directory under ~\IoT. There's also a configuration file that goes in there to hold some values, The web server sits on a desktop or embedded-linux device and just makes Basically, what I'm developing this for is eLua development. More for I will come back in a few days once the documentation is online. This is entirely a new concept to manage ESP8266 devices and their source On Mon, Jul 27, 2015 at 1:35 AM, zeroday [email protected] wrote:
|
|
On Mon, Jul 27, 2015 at 1:35 AM, zeroday [email protected] wrote:
Then when your esp8266 is 'in-production', you can easily jump over to it |
You're not alone with this. I don't see how those comments are relevant in discussing the structure and organization of the NodeMCU firmware project/community.
I agree, http://bbs.nodemcu.com/ would probably be more appropriate but since that forum is mostly Chinese I suspect many contributors aren't active there (myself included). You can still open a thread there, post a link to it here, and then close the issue if you like. Anyway, thank you very much for reaching out to us. It's a relief to see some of the project owners realize the project may need some guidance, governance or rules in order to prosper and continue to be relevant. I have pretty clear ideas on how a GitHub project should be run and I'm happy to share them once you decide whether you want to continue the discussion here or elsewhere. |
|
I feel that the project could benefit from some the knowledge / experience / contributions from the wider contributors outside the core node MCU dev team. At the moment we have info spread across multiple repositories: this git source hierarchy, the wiki, the nodeMCU online docs, the nodeMCU hosted resources such as it bbs and third party resources such as those hosted on esp8266.com. Some rationalisation and normalisation of these would help, e.g. around some git hierarchy so that the same git contribution techniques could be used across the entire set. We should also properly separate out end-user support from firmware development, with end-user support left to the nodeMCU bbs, esp8266.com and StackOverflow, etc.. Any issues which are user "howto" Qs here should be immediately closed referring the OP to the above. |
|
@marcelstoer , thank you! |
|
As for the first problem, Guide is always a big problem for almost any opensource project. And the dealling ways are always the same. We can let the users to write them. 2.We need to have more labels for issue list. To sort them clearly, and have more manger. So as for me, the problem is at The guys who manage this project dont have enough time to maintain, but the guys who have time don't have authority to do so. The methods that I think will work are->
|
|
Ok, here we go...
Actually that's two questions. Support as few branches as absolutely necessary. You already found out that long-lived branches are a pain to maintain. IMO besides master you should only have dev as long-term branches. Everything else should be short-lived. If, based on the reported issues, there's a critical bug in master for example you can create a patch branch that only lives for a few days until everything related to that issue is resolved. Guidelines for contributors are extremely important and GitHub has good means to make that very painless: https://help.github.com/articles/setting-guidelines-for-repository-contributors/ (links to good examples).
I suggest you close all those "help, why doesn't this Lua code work" issues quite aggressively. There are currently 160 open issues and it's quite demotivating for anyone trying to help to sift through them to find real bugs he/she could work on. Direct I-need-help issues to www.esp8266.com/viewforum.php?f=17 or http://stackoverflow.com/tags/nodemcu.
Of course you could always read a book on the subject by people who know (How to Run a Successful Free Software Project, even in Chinese). Below are just my 2 cents. Fact: most OSS projects are run by passionate folks part-time in their spare time. You need at least enough time to nurture the community incl. the core contributors or you should find new maintainers. Not every contributor has to be a top-notch C-coder. I, for example, am not but I can still work on infrastructure (Travis-CI), help out managing the issue list, write documentation or provide external services such as the cloud build. In order to reduce the distraction (i.e. unproductive time) for contributors the project should be self-explanatory for both users and developers. Good documentation is crucial so people don't have to ask. What's the first thing visitors to the GitHub repo see? The README.md. It must contain all relevant information and must always be up to date for the respective branch (same for CONTRIBUTING.md)! What is also very important for me is that what you ship must be well tested and stable. If not, you spend a lot of time just managing the issues or answering questions when you want to rather spend your time on coding. I realize automated testing isn't easy for IoT projects (see #516). Therefore, manual verification is even more important. I'm sometimes irritated how quickly PRs are merged. I suggest you only merge a PR if you have thoroughly verified it yourself or 2-3 people you trust haven written an "ok" comment. As suggested by @MarsTechHAN you should introduce issue labels (e.g. bug, feature, one per branch, one per module).
Not sure what policy you refer to.
In what way? As Terry said the English natives are certainly willing to help out when it comes to proof-reading and correcting documentation. To answer issues or write comments your English is certainly good enough. |
|
Thank you @marcelstoer @MarsTechHAN |
|
A few days ago I responded elsewhere #449. I will not repeat it here... |
I agree with what several of the others have said about issue labels and directing "help me with lua" sort of issues to other sites.
Choose some people that you trust and who have already contributed a bit and offer to make them collaborators on the repo (or members of the nodemcu organization). Then they can help you with the burden of sorting through issues, validating PRs, etc. Anyone who replied to this thread is probably a good candidate. Maybe set up a irc/gitter/whatever for your newly promoted team to be able to discuss things. One other point about docs, the api page is becoming awkward due to how many modules there are. I think it should be split into one page per module (regardless of whether they remain wiki pages or are moved to some other location). |
I'm currently fiddling with api updates for u8g - and fully agree with this one. |
[OT] |
|
Right, I stumbled over this as well. |
Let me pick up here, even at the risk of potentially further diverting from the core topics. My stance on API documentation in general is that it belongs into the source code. Why? Because you need to document the source code anyway, right? And then you generate the official API documentation (HTML, PDF, whatever) from the source code during the build. A great example for such a system is Swagger which I use to document REST APIs in my non-NodeMCU world. The idea is that you annotate the source code (implementation of your REST API) and document it. Swagger then generates a fully executable documentation based on the annotated source. |
|
I feel that we really really need to take a simple firm line on the scope of this issues list. The active community has an aim of contributing to the development of the firmware, but the majority of the issues raised here are by Lua developers who keep asking Qs like "My app doesn't work, so is there a bug in Lua?" or "Can I use Lua to solve world hunger?". Answering all of these just takes up too much time. I feel that we should have an issue or some other announcement which strictly defines the scope of the issues list as:
and provides alternative links for issues outside this scope, e.g. for SDK feature enhancements (the Espressif bbs) and Lua application issues (e.g SO and esp8266.com) . Any other issues should be closed referencing this statement and we should avoid entering into discussion on these issues once closed. |
|
If these sort of guidelines were clearly stated in the README, this recurring problem would go away. |
|
@marcoskirsch Marcos, I am a little more cynical. For this to go away (i) posters would have to read the README, and (ii) do as it suggests. OK, some might do, so the "false issue" rate might drop by 30% or so, but it would help if we could just say "Please see XX " (some standard link), and better if I then had the permissions to close the issue myself. |
|
Thank you for all these suggestions! and thanks for everything! |
|
Hard to find out contact info from github. forgive my rudeness. |
|
I think it might be worth using https://readthedocs.org/ for documentation. |
Thanks. It might also be worth reading other people's comments in this long thread before posting "suggestion dups" 😉 |
|
Doh! I must have missed that when I skimmed though the comments. |
|
I've never touched Lua before NodeMCU. For some, it may be unclear if the problem they are having is a NodeMCU problem or a Lua problem. A list of Lua-specific resources may be helpful in I feel that (on GitHub anyway) The maintainer closing all issues determined to be "not a NodeMCU problem" should provide a friendly link to |
|
I'd go as far as recommending to drop the wiki entirely and use nodemcu.github.io as the central place for all documentation, tutorials, and links to other resources (like discussion boards). GitHub wiki's are a bit obscure and can become stale quickly. |
|
(you can throw a |
+-1 😉 As much as I like GitHub Pages myself I still believe that the API documentation should be maintained in the same repository & branch as the source code. That is our best chance to enforce that each PR is complete and includes the necessary documentation updates. As for |
|
I think that the tests here should be:
If the answers are yes and no respectively then the documentation should be in (or in buildable form) the nodeMCU/docs tree. eLua has a build process which constructs all of the standard eLua documentation in HTML format from its docs hierarchy. OK, the latest version is also online but because this is in the repo, anyone using an old version or branch has the option of rebuilding the docs for that branch and also the normal git versioning, diff and blame functions work as standard. The essential yes/no stuff here is the nodeMCU core and library API documentation. Things like white papers and FAQs (which by their nature evolve over time) are perhaps wiki stuff as they aren't part of the configuration controlled source base. Any wiki would do, IMO as long as it is a single well known one and under general control of the project. |
|
We have currently 115 open and 230 closed issues. Ignoring the closed issues for the moment, the open issues probably fall into 4 categories:
My view on 3 and 4 is that these should be allocated to the "won't fix" and "help wanted" labels; cross referenced to a standard advice issue and closed, but not locked (unless the conversation goes really off the rails). The difference between 1 and 2 needs a bit of explanation, by comparison to how PHP is set up. There, the core development team maintain the PHP runtime and a core set of libraries that are part of the distribution. However there a lot of extensions supported through PECL (the PHP extension library) which is kept separate from the core. I see that a lot of our "bug" issues aren't really to do with the core software, but to some specific extra module or "sketch" (in Arduino terms), so fixing any issues relating to these isn't really for the core team to get distracted by. So what I propose is:
Any comments or reactions? |
|
I second Terry's proposal, especially the separate repo for extensions. Only comment that I have is for the fourth category of issue. If a user has On 25 August 2015 at 16:22, Terry Ellison [email protected] wrote:
[image: --] Nathan Bookham |
|
I agree with most of what Terry proposed.
Most cat-4 issues / remember stem from pure laziness to actually search for an read the available documentation.
Don't complicate matters for now. I think there are enough other issues this project should tackle first (i.e. as discussed above in this meta issue). How would you define core / non-core? How do you build the firmware if extensions are in a separate repository? |
|
"Help wanted" issues kind of suck. Some people like them in GH issues, but to my mind the more appropriate place is a mailing list, forum, or chat channel. Of course there needs to be that place where users can go to get questions answered. Would like to hear other opinions on whether "help wanted" issues should be addressed (if you think they should be) instead of closed with links to other resources. |
|
There are places people can ask "help wanted" questions: http://www.esp8266.com/viewforum.php?f=17 or http://stackoverflow.com/tags/nodemcu to name two. IMHO such issues should be closed here right away with a standard answer. |
|
I'd also favour @TerryE's approach. And let's see how extensions would be defined, but that's a subsequent step. Getting the issue list somehow sorted is most important at the moment, IMO. |
The available documentation is seriously lacking though, so I'd prefer TerryE's approach. I am willing to lend a hand btw. This project taught me a lot about lua, C and who-knows-what-else, would love to give something back! |
This seems to be a common thread and improving the documentation should be an issue in its own right. Because a material rework of official / controlled documentation can take a lot of time and effort, my workaround was to start my Unofficial FAQ and it is on the esp8266 wiki so anyone is free to collaborate with me on this. I've got about 50% of what I want to put in, but as a page it's already too long, so I need to reorganise the content. @nodemcu @vowstar @MarsTechHAN what do you think of this last discussion of the last two days in general? You guys are the major stakeholders here. |
|
Just in case anyone is interested I've pulled the open issues using the github V3 API into a spreadsheet, so I can have a first pass at categorising them and labelling them. Here is a copy of the ODS if anyone also wants to have a scan. I'll report back in a couple of day giving my analysis and recommendations. |
|
Things have changed for the better by now. |
well, It's not a good place to discuss here on a issue maybe:)
but I need some professional suggestions and help of how to make this project clean and organized,
as #449 discussed. and more to sort out.
1, what is the good/popular branches setup. the clearly documented contribution guide?
let people know how to build a stable/test or most new features bin.
2, how to sort out issues, what kind of issues can be opened and stay as a "real" issue here?
some issues like this one, can it be posted here or some where else like forum?
3, I want to make this project a long-run project, but some times too busy for this, currently we still do part-time in this project. any suggestions of how to make this project a really good opensource iot project.
4, what is a good police for those cool guys who want to participate more?
5, for now me and others are from China, not English native speaker, some time it's a problem. anyone can help this?
thank you guys in advance. any advise would help!
The text was updated successfully, but these errors were encountered: