improve git functionality for vapor new

[p4t5h3]

Currently every project created with vapor new is based on the vapor example project. That results in boilerplate code which is more suitable for demonstration purposes than actual starting ground for new projects. In example the mustache example functionality and dependency likely is going to be removed every time.

The solution would be to introduce the example argument for the vapor command line application, which creates an new project based on the example.
In parallel the new argument will be modified to create a barebone project with just the minimal content necessary to get going (requires a new repository as a source). In addition there is an option (argument --template, other suggestions welcome) to specify the repository to use as the template for creating a new project.

This enables new starting points when creating new projects.

Example

vapor new Vaporizer

Creates a new project in the Vaporizer directory based on the minimal, default project template. Invokes dependency installation and build automatically (vapor build).

vapor new Vaporizer --template=https://github.com/alomvar/vapor-blog-template

Creates a new project in the Vaporizer directory based on the provided project template (a Git repository). Invokes dependency installation and build automatically (vapor build).

vapor example

Creates a new project in VaporExample based on the official Vapor example project. Invokes dependency installation and build automatically (vapor build) and runs it afterwards.

[tanner0101]

Can we merge #214, #215, and #216 into a more comprehensive issue about improving the vapor new functionality?

[p4t5h3]

We could, it just seemed to be a good idea to keep this actually separate concerns in separate issues and pull requests, even though they are simple. By experience doing small steps is better than a big leap.

[tanner0101]

That makes sense. But, I'm pretty sure this could be handled in one PR and won't be very much code. If it were big, unrelated features that would make more sense to keep them separate.

[p4t5h3]

I left out #214 because I already created a branch and by now there already is a badly named pull request (#222). Thinking and rewriting the issue shows that combining #215 and #216 actually is a good idea.

[tanner0101]

You can change all of the information in a PR, including the name. GitHub is very dynamic. :)

[p4t5h3]

By stripping down the Vapor example to essential parts I created a new project template:
https://github.com/alomvar/vapor-template

Please take a look. Further steps would be agreeing on it and then moving it to qutheory so changes to the Vapor CLI can be made.

[tanner0101]

I'd like to at least include the Controllers, Models, Middleware folders, even if their empty. We can just put a .gitignore or .gitempty in them, right?

[p4t5h3]

Yeah, right, at first I thought more minimal, less opinionated would be better but without controllers, models and alike there actually is no point to use Vapor instead of in example static HTML files.

[p4t5h3]

I added the directories with .gitignore files and upgraded it to Vapor 0.8

Closing this issue was not intended.

[tanner0101]

What would you think about vapor new <name> automatically using the template version and a new command like vapor example cloning and running the example?

[p4t5h3]

I am not sure what you mean, maybe I just described my idea not clear enough. I updated the issue comment above with examples. However I picked up on the idea that providing a name for creating the example project is not necessary. But I think it is still for normally creating a new project.

In case of the example, running it would be another nice addition, too.

[timominous]

@tannernelson @alomvar I think using urls gives the user more control although I don't have anything against named templates. Maybe we should take a look on how heroku handles buildpacks?

[p4t5h3]

@timominous It depends how many named templates should be available. If there a few, official and well maintained that is easy to do with a dictionary inside the Vapor CLI. Otherwise it would require some additional infrastructure and thus hassle (if I did not forget something).

I assume there will be an official Swift package registry at some time which can handle the resolution of names to repositories, as it happens with in example Composer packages on Packagist. As long as Swift package manager itself relies on Git repository URLs we should maybe do so, too.

Anyway, named templates or not, repository URLs should be possible either way.

[tanner0101]

@alomvar the updated issue comment looks perfect 👍

[loganwright]

I really like the idea of implementing a url parameter, perhaps we need some way to define what exactly a template is and how we interact with it. It could be as simple as an empty repo that we clone completely.

This will affect some parts of our tooling, for example, some features rely on the application being named App. This isn't an actual requirement, but it is a requirement of our CLI and it would be nice to be able to evaluate a template.

Maybe include a mention like:

This template doesn't appear to be a properly formatted Vapor template, some CLI commands may be unavailable.

Ideally there'd be a way to prevent just any repo from being cloned.

I'm also partial to username/name-of-proj defaulting to github.

[finestructure]

Regarding the template parameter: As a techie I always wonder how stuff works under the hood. If the template parameter is a URL I immediately know where it's from and where I can go look for more details. I suspect that's true for a lot of the users as well.

So I'd go with just a URL rather than a mapping that you need to maintain.

[p4t5h3]

First: Should this be "moved" to the Vapor CLI issues? I do not know how except for closing it here and opening a new one there.

@feinstruktur If implemented as @loganwright described it, it would still be transparent because user/repository would only be a shorthand form of https://github.com/user/repository.git without any mapping.

[tanner0101]

Create a new issue in the Vapor CLI repo, then reference this issue from there (using the qutheory/repo#number syntax)

[collinhundley]

I came here because I was looking for the same thing: a barebones version of the project to start from. The example project is nice but it would be useful to have something more basic to use as a starting point.

On a related note: what's the recommended way to rename a Vapor project? @loganwright mentioned that the application itself needs to be called App, but what about the Xcode project? I attempted to change one using Xcode's rename tool, but it broke some dependencies.

[loganwright]

I'm going to close this branch, it's gotten a bit stale and we've improved some of the git functionality quite a bit since this originally went up. If we have further discussions, let's reopen a thread @qutheory/vapor-cli

Thanks to everyone for participating!

[tanner0101]

You can now do vapor new <name> --template=... and clone any repository. It will update the Package.swift name with whatever <name> is. Now it's up to us to create new templates.