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.

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

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

Open
harvv opened this issue Jan 9, 2019 · 3 comments
Open

Comments

@harvv
Copy link

harvv commented Jan 9, 2019

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
Copy link
Member

utzig commented Jan 9, 2019

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
Copy link
Member

utzig commented Jan 9, 2019

@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
Copy link
Author

harvv commented Jan 10, 2019

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants