Reference links in generated project

[snicoll]

Related to #279

After a quite involved brainstorming with @bclozel we came to the conclusion that rendering links in the front page is the wrong call. There are a lot of information on this page already and the prototypes that we've built clearly show that it does not help at all.

Our reasoning is that we must support our goal to let users work in their IDE as soon as possible and not forcing them to stay on the page to collect URLs. We believe that generating a markdown/asciidoc at the root of the project with some information would be quite interesting. As a first iteration we could render the links, if any.

I am not sure that we want to call that README.md and it should probably be in the .gitignore for the time being. Maybe HELP.md ?

[wilkinsona]

For the lazy, can you explain in this issue what you mean by "link" and provide some examples of what may appear in the HELP.md file?

[snicoll]

@wilkinsona there are two issues link to this issue (see in particular #279 (comment)). This is about adding links support to dependencies in the metadata. That way we can provide URLs to section of the doc, to a guide, to a home page for a 3rd party starter, etc. Clients are free to use that information any way they like (still TBD) and we've done some experiment for our own web interface.

That file would contain the links for the dependencies that you've selected when generating the project. Let me know if you need more context for this, thanks!

[bclozel]

Let's discuss the format then. Here's what HELP.adoc could look like for an application generated with the "web" and "jpa" starters.

= Application name

Application generated with http://start.spring.io/[Spring Initializr].

== Starter information

Web:

* https://spring.io/guides/gs/rest-service/[Guide: getting started building a REST service]
* http://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-developing-web-applications.html[Reference: developing web applications]

JPA:

* https://spring.io/guides/gs/accessing-data-jpa/[Guide: Accessing Data with JPA]
* http://docs.spring.io/spring-boot/docs/current/reference/html/boot-features-sql.html#boot-features-jpa-and-spring-data[Reference: JPA and Spring Data]

[dsyer]

I think it's better to use README.md (not adoc and not HELP). It's already a standard location that gets everyone's attention and special treatment from GitHub etc. IMO we should start with that instead of inventing our own new file name convention. We can always move it later if people ask.

[snicoll]

The reasoning why it's not named README is because I don't think this is something that a user should commit to its own repo. It is something we provide for them, not something they should publish as part of their app.

I am with you on the .adoc vs. .md. We need to chose whatever format is natively recognized in the IDE.

[wilkinsona]

The reasoning why it's not named README is because I don't think this is something that a user should commit to its own repo

I think people might want to commit it. Having links to the documentation/guide for each thing that's being used could be useful for people joining a new team, for example.

I am in favour of it being README.

I am with you on the .adoc vs. .md. We need to chose whatever format is natively recognized in the IDE.

Another +1 for Markdown.

[snicoll]

Let's go with README.MD