search

apache / mynewt-documentation

Apache MyNewt Documentation
18 stars 47 forks source link

Doc for sample project is out of sync with latest repo/tool versions #65

Open harvv opened 5 years ago

harvv commented 5 years ago

As of Jan.09.2019, when following the instructions from mynewt-documentation/docs/get_started/docker.rst and then mynewt-documentation/docs/get_started/project_create.rst , the version of the newt tool in the "latest" docker image will be 1.3.0 (cited as 1.1.0 in docker.rst) "user@~/dockertest/myproj$ ../newt version Apache Newt version: 1.1.0"

...and when following steps in project_create.rst, with the default project.yml file 'newt new myproj' creates, it will pull down version 1.5.0 of the project/core ...which when executing the command to run a test after the 'install', will yield this error:

" newt test @apache-mynewt-core/sys/config

Error: This version of newt (1.3.0) is incompatible with your version of the apache-mynewt-core repo (1.5.0); Please upgrade your newt tool to version 1.5.0 "

Since this is a guide intended for the inexperienced Mynewt OS and newt tool user, it's highly problematic that it isn't completely error/mistake free

utzig commented 5 years ago

Thanks, we'll update it today. The latest version of docker in our repo should have 1.4.1 but I think it was not pushed, so we'll update to 1.5.0 today and push to the hub. Regarding the docs, we'll update as well but there should be no changes apart from the version shown in those steps...

utzig commented 5 years ago

@harvv Docker hub is updated now, so you should be able to get the latest version with: docker pull mynewt/newt.

@aditihilbert Is there a way to maintain these documentation numbers always up to date without manually editiing on every release?

harvv commented 5 years ago

thanks for the fix. also just FYI, I originally worked around the issue by modifying the project.yml file like so: " repository.apache-mynewt-core: type: github vers: 1.3.0 " Suggestion: if there isn't an easy way to auto-magically keep the doc. numbers up to date, then perhaps a better-than-nothing "fix" might be to mention in the docs that if someone runs into the "incompatible version" error, then a temporary workaround to get them going is to mod the project.yml file to match versions

Also as an aside:
it took some digging and intuition to figure out what the vers field values are, and how they map to what's in the github repo. Might be worthwhile to bulk up the docs on that. (though I will concede that's lower priority than what you probably have queued up on the To-Dos for this project).
e.g. it's not totally clear that instead of what was in the file before as a value for vers ("1-latest") , can actually be a github release version number. The project_create doc just says: " Changing vers to 0-dev will put you on the latest master branch. This branch may not be stable and you may encounter bugs or other problems. Note: On Windows platforms, you will need to change vers to 0-dev and use the latest master branch. Release 1.0.0 is not supported on Windows. " .....which is pretty "black-box" w.r.t. to the value->branch/tag mapping.