TODO

High level goals

• Make it easy to add new guides (a guide comprises a human readable markdown file and a corresponding bash script)
• Ensure the script gives us reproducible results, where we can assert etc
• Reference the script (commands and output) from the corresponding markdown file
• Therefore have the entire guide (markdown and script) remain in sync

Feedback

• @goinggo: we will likely want to wordsmith the markdown in Google Docs (or similar) first, and then "merge" with the script in the markdown file later
• @dlsniper: would it be better to split the single README into multiple files? More like pages/sections of a book? Easier to absorb detail this way?

Guides to write

• Finish/improve the Buffalo example as a guide for dep migration
• "How do I exclude a dependency's test dependencies?" - a common question in #vgo. Write a guide that explains what's going on here
• "How do I structure a mono-repo? Do I have just one go.mod at the root? How do I decide where to place a go.mod?" - a less common question in #vgo, but a good one to tackle
• A guide on how Hugo migrated from dep to vgo - perhaps ask @bep to help finesse this one?
• "How do I use custom import paths with vgo?"
• Using internal packages with modules
• How to use vgo get X@branch
• Using vgo vendor - how, and why would you do it?
• How and when to use a proxy (including a proxy to the local file system)
• Using vgo run (with the new package argument, when supported), particularly with module versions >= 2
• Using GOPROXY
• "How and why would I use go.modverify?"
• "How do I work with forks?"
• "My git repo has a number of packages within it (but it's not a classic mono-repo). How do I decide which packages should be separate modules? What are the pros and cons of having a single top-level module vs more modules?"
• "How can I grep all of myapp's dependencies?" (reuse part of this answer)
• "How do I use tools like godef with vgo?"
• "How do vgo and -X ld flags work together?"
• "How do I declare and work with submodules?" (needs a resolution on this issue)
• "How do I work with projects/packages that have not yet been converted to by Go modules?" (possibly borrow from https://github.com/golang/go/issues/25674)
• Example using -getmode=vendor, -getmode=local
• vgo get of module with no package in root based on https://go-review.googlesource.com/c/vgo/+/120995
• vgo list -m examples based on https://go-review.googlesource.com/c/vgo/+/120198
• Direct vs indirect module dependencies
• Running vgo test ./... from the root of a repo
• Test that vgo list -m -json works in the presence of errors
• Add example that uses CLI tool to edit go.mod instead of hand editing (e.g. replace)
• Example that depends on both v1 and v2 of a module
• Example that uses go list... and show it ignores submodules
• https://github.com/golang/go/issues/27457#issuecomment-419364867 as of https://github.com/prometheus/prometheus/commit/068eaa5dbfce6c08f3d05d3d3c0bfd96267cfed2
• How to use go list for packages/modules; i.e. to list test dependencies
• Using go mod
  • go mod edit and its various flags
  • ...
• Visualising dependencies using go mod graph and dot

TODO

• Automate the building of a table of contents in this README
• Switch from horrendous bash-based Github API access to a simple Go program that has various commands
• Tidy up common script elements into a sourced file (that egrunner then ignores), e.g. git config --global advice.detachedHead false, assert etc.
• Implement some sort of hash-bashed caching of README.md + script.sh + egrunner + mdreplace + vgo version + ...