Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Rework the README file considerably #769

Merged
merged 17 commits into from
Dec 5, 2015
Merged

Rework the README file considerably #769

merged 17 commits into from
Dec 5, 2015

Conversation

nickandrew
Copy link
Contributor

Nobody had updated the README file from 0.9.5 to 1.4.0 and so that was my starting point.

Looking at the README from the point of a new user, information you need to know wasn't there or was presented in the wrong order.

  • Restructured to remove a lot of irrelevant information (e.g changelog)
  • Reordered to show general features first, then show off the platform capabilities, then explain how to build it, how to configure it, how to flash it and then how to run it after flashing
  • Added info about esptool (the lack of doco confused me initially as a Linux user, as I couldn't use nodemcu-flasher and there was no note in the README to say it was for Windows only)
  • Updated info about Marcel's cloud build server (you do need to tell people to build the dev branch or they will build from master)
  • Added a link to the docker containerised build, which is the easiest way to build a firmware with your own patches
  • Added sufficient detailed build instructions for anybody who really wants to install the toolchain
  • Updated the list of optional modules in user_modules.h
  • Added instructions on tagging your own builds
  • Added instructions on changing the boot time serial interface rate
  • Described the GPIO0 conditions for normal boot and for flash upgrade
  • Gave more detailed instructions on what needs to be flashed
  • And how to connect the device
  • And the least interesting code snippets went down the bottom of the document where they can be cleaned up later.

After merging this pull request into dev I'd suggest also merging it into master, or probably nobody will see it until dev itself becomes master.

@nickandrew
Update README base to 1.4.0
7b65613 
Signed-off-by: Nick Andrew <nick@nick-andrew.net>
@nickandrew
README: Clean up the language
64a2189
@nickandrew
README: Remove unnecessary changelog
de634a9 
Changelog is in the git history, or major changes should be noted
in CHANGELOG.md

Signed-off-by: Nick Andrew <nick@nick-andrew.net>
@nickandrew
README: Move the simple programming examples up
b27fc6f 
The README is presently quite unreadable. The simpler examples of
programming an already-flashed ESP8266 are moved up, to give the
new user the flavor of what is possible with NodeMCU.

Instructions to build the firmware will follow.

Signed-off-by: Nick Andrew <nick@nick-andrew.net>
@nickandrew
README: Add usable build instructions
1aa5efc 
Put Marcel's online build server first, as this will be the go-to for
new users. Note that they should build 'dev' not 'master'.

Next, list the docker image which will build from your checked-out
repository and possibly including your own changes.

Finally, list the prerequisites if you want to build it all yourself,
including the sequence of commands (same as the docker image uses).

Signed-off-by: Nick Andrew <nick@nick-andrew.net>
@nickandrew
README: More work on the build options
20bca02 
List the latest set of modules in the example on disabling modules.

Show which file to edit to tag your firmware to identify it on boot.

Signed-off-by: Nick Andrew <nick@nick-andrew.net>
@nickandrew
README: More tweaking of the summary text
c8f9f4c 
Add all the latest module names too.

Signed-off-by: Nick Andrew <nick@nick-andrew.net>
@nickandrew
README: Temporarily remove the 'download' button
c1fd5d4 
Remove the download button until a 1.4.0 release is pushed to github.

Signed-off-by: Nick Andrew <nick@nick-andrew.net>
@nickandrew
README: Tidy the sample code
7b1a371 
Signed-off-by: Nick Andrew <nick@nick-andrew.net>
@nickandrew
README: Remove GPIO NEW TABLE
e9091cc 
It's in the API documentation and doesn't belong in the top-level README.

Signed-off-by: Nick Andrew <nick@nick-andrew.net>
@nickandrew
README: Update building and flashing instructions
7731592 
Make it more obvious to run file.format() after flashing.

Signed-off-by: Nick Andrew <nick@nick-andrew.net>
@nickandrew
README: Flashing and connecting
7d05a25 
Signed-off-by: Nick Andrew <nick@nick-andrew.net>
@nickandrew
README: Remove the <br/> tags
81db4ae 
Change to Markdown list or table.

Signed-off-by: Nick Andrew <nick@nick-andrew.net>
@nickandrew
README: Expand and update the Resources list
e1e1cde 
Signed-off-by: Nick Andrew <nick@nick-andrew.net>
@nickandrew
README: Setting the initial serial interface rate
44adcd5 
Signed-off-by: Nick Andrew <nick@nick-andrew.net>
@nickandrew
README: Tidy up the user interface tools
8eb3fba 
Signed-off-by: Nick Andrew <nick@nick-andrew.net>
@nickandrew
README: Tidy ugly looking uart.setup() call
703d55d 
Signed-off-by: Nick Andrew <nick@nick-andrew.net>
@marcelstoer
Copy link
Member

Thanks for the PR.

Please consider https://github.com/nodemcu/nodemcu-firmware/blob/dev/CONTRIBUTING.md next time. It would have helped to learn about your intention before you started. Among the collaborators we have been discussing what to do with the README not too long ago and I've been working on it already.

Also, please squash your commits into one (e.g. by following http://www.andrewconnell.com/blog/squash-multiple-git-commits-into-one) as requested in CONTRIBUTING.md.

@nickandrew
Copy link
Contributor Author

Hi Marcel,

I did read CONTRIBUTING.md before starting, but I noted that it said

This is just one way of doing things. If you're proficient in Git matters you're free to choose your own.

I've been working in git for about the last 8 years. I didn't squash my commits because they are logical units of change, and they're all changing the same file. Chunks of text were moved around. If I had presented a single large commit you'd have had no idea what had changed. As it is you can understand the individual changes, and when it comes to review, you might decide not to pick up all the changes I made. Squashing my commits prevents that happening.

One thing I forgot to say in the PR is, if you want to see what the README looks like after all the changes, it's here: https://github.com/nickandrew/nodemcu-firmware/tree/tidy-readme

@marcelstoer marcelstoer mentioned this pull request Nov 17, 2015
Closed
@marcelstoer
Copy link
Member

Fair enough...I don't necessarily need to agree to understand your reasoning 😉. Thanks for explaining, I see your point.

This was referenced Dec 3, 2015
Closed
Closed
marcelstoer added a commit that referenced this pull request Dec 5, 2015
@marcelstoer
Merge pull request #769 from nickandrew/tidy-readme
09650c0 
Rework the README file considerably
@marcelstoer marcelstoer merged commit 09650c0 into nodemcu:dev Dec 5, 2015
@marcelstoer
Copy link
Member

Even though once #771 and #774 are completed the README.md will look quite different, this is still valuable to have.

@nickandrew nickandrew deleted the tidy-readme branch December 5, 2015 14:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@nickandrew @marcelstoer