[CLI] Improve readme of a new project #4981

frbuceta · 2020-03-28T15:47:45Z

Until now, new projects and extensions did not have a README file with useful information. I want to put new things to help improve this default file.

Help links, tutorials or examples ... Anything that can help those starting with Loopback

Checklist

👉 Read and sign the CLA (Contributor License Agreement) 👈

npm test passes on your machine
New tests added or existing tests modified to cover all changes
Code conforms with the style guide
API Documentation in code was updated
Documentation in /docs/site was updated
Affected artifact templates in packages/cli were updated
Affected example projects in examples/* were updated

👉 Check out how to submit a PR 👈

packages/cli/generators/project/templates/README.md.ejs

packages/cli/generators/project/templates/package.json.ejs

raymondfeng · 2020-03-28T17:43:32Z

packages/cli/lib/project-generator.js

@@ -226,6 +226,7 @@ module.exports = class ProjectGenerator extends BaseGenerator {
      this.destinationPath(''),
      {
        project: this.projectInfo,
+        cliVersion,


Is cliVersion used in a template?

Yes, I am putting a message similar to what Angular says when you create a project with "this has been generated with Loopback CLI version X"

Please note we already captures cli version in .yo-rc.json.

I know, this that I am putting in the README file only has a visual and informative character. It has no other functionality

@frbuceta , thank you for this PR. It is a good idea to add more content to this readme.

dhmlau

@frbuceta, thanks for your PR to beef up the project template. I have a few comments.

packages/cli/generators/project/templates/README.md.ejs

dhmlau

LGTM with one minor change.
Please wait for approvals from @raymondfeng and @nabdelgadir to make sure their feedback is addressed. Thanks again @frbuceta.

packages/cli/generators/project/templates/README.md.ejs

emonddr · 2020-04-06T18:39:30Z

packages/cli/lib/project-generator.js

@@ -226,6 +226,7 @@ module.exports = class ProjectGenerator extends BaseGenerator {
      this.destinationPath(''),
      {
        project: this.projectInfo,
+        cliVersion,


@frbuceta , thank you for this PR. It is a good idea to add more content to this readme.

Set version to 0.0.1

dhmlau · 2020-04-07T01:28:09Z

@emonddr, i'd like to assign this PR to you. Could you please help @frbuceta on this PR so that it can land? Thanks.

emonddr · 2020-04-07T14:44:43Z

@frbuceta , looks like you already implemented my suggestions, so I don't need to push any commits to help you along. :)

packages/cli/generators/project/templates/README.md.ejs

emonddr · 2020-04-07T15:21:36Z

I generated a new application using this updated template.
Here is what it looks like at the moment

Based on this image, I have a few other suggestions

Change Run section title to Starting the application
Change CLI Reference to Using CLI Commands

This way all 3 substeps of First Steps have a title that consistently finish with ing .

frbuceta · 2020-04-07T16:27:43Z

I generated a new application using this updated template.
Here is what it looks like at the moment

Based on this image, I have a few other suggestions

Change Run section title to Starting the application

Change CLI Reference to Using CLI Commands

This way all 3 substeps of First Steps have a title that consistently finish with ing .

I see it by setting the file in MARKDOWN mode and then with the key combination CONTROL + SHIFT + V

frbuceta · 2020-04-07T16:28:32Z

We are doing a good job

raymondfeng · 2020-04-07T17:21:23Z

packages/cli/generators/project/templates/README.md.ejs

+
+Refer to [Command-line interface](https://loopback.io/doc/en/lb4/Command-line-interface.html) for the full list of LoopBack 4 commands.
+
+### Adding Additional Dependencies


Do we want to mention lb4 upgrade to handle project dependency upgrade for newer LB versions?

It is currently documented at this link

raymondfeng · 2020-04-07T17:24:35Z

@frbuceta It would be hard to maintain README generation. What about we add a new page to loopback.io to capture the post-scaffolding steps? The README can just have a link to the page so that developers can learn the initial project layout and what they can do as next steps. The page will be a follow-up to https://loopback.io/doc/en/lb4/Getting-started.html.

See #4847

packages/cli/generators/project/templates/README.md.ejs

frbuceta · 2020-04-07T19:31:47Z

@frbuceta It would be hard to maintain README generation. What about we add a new page to loopback.io to capture the post-scaffolding steps? The README can just have a link to the page so that developers can learn the initial project layout and what they can do as next steps. The page will be a follow-up to https://loopback.io/doc/en/lb4/Getting-started.html.

See #4847

Something like..?

Getting Started

If you are starting we recommend that you start here

First Steps

Starting the application

Starting the application is as easy as:

npm start

....

raymondfeng · 2020-04-07T20:53:45Z

@frbuceta Yes, what I have in mind is that we generate README with high-level steps, such as:

Getting started
Try it out the first (ping) API
Get familiar with the project
- Project layout
- Inside a LoopBack app
What's next
- Add models, datasources, ...
  ...
Maintain project license and copyright
Upgrade project dependencies
Join the community (loopback.io, git, slack, ...)

frbuceta · 2020-04-07T21:50:55Z

@frbuceta Yes, what I have in mind is that we generate README with high-level steps, such as:

Getting started

Try it out the first (ping) API

Get familiar with the project

Project layout

Inside a LoopBack app

What's next

Add models, datasources, ...
...

Maintain project license and copyright

Upgrade project dependencies

Join the community (loopback.io, git, slack, ...)

This would be for the "Get started" page?

raymondfeng · 2020-04-07T22:16:08Z

This would be for the "Get started" page?

Probably a new page such as Work on your first LoopBack 4 project. The README will have pointers to the new page as follow-up steps after Getting started.

My main point is not to add too much detail the README template. The README should have high-level post scaffold instructions that link to our docs.

dhmlau · 2020-08-19T13:29:32Z

We just switch the contribution method from CLA to DCO, making your contribution easier in the future. Please sign the commits with DCO by amending your commit messages with -s flag and push the changes again. If you're using the command line, you can:

git commit --amend -s
git push --force-with-lease

Please refer to this docs page for details. Thanks!

frbuceta requested review from agnes512, emonddr and nabdelgadir as code owners March 28, 2020 15:47

frbuceta requested a review from dhmlau March 28, 2020 15:48

raymondfeng reviewed Mar 28, 2020

View reviewed changes

packages/cli/generators/project/templates/README.md.ejs Outdated Show resolved Hide resolved

raymondfeng reviewed Mar 28, 2020

View reviewed changes

packages/cli/generators/project/templates/package.json.ejs Outdated Show resolved Hide resolved

raymondfeng reviewed Mar 28, 2020

View reviewed changes

dhmlau reviewed Mar 29, 2020

View reviewed changes

packages/cli/generators/project/templates/README.md.ejs Show resolved Hide resolved

packages/cli/generators/project/templates/README.md.ejs Outdated Show resolved Hide resolved

packages/cli/generators/project/templates/README.md.ejs Outdated Show resolved Hide resolved

dhmlau added community-contribution CLI developer-experience Issues affecting ease of use and overall experience of LB users labels Mar 29, 2020

nabdelgadir reviewed Apr 2, 2020

View reviewed changes

packages/cli/generators/project/templates/README.md.ejs Outdated Show resolved Hide resolved

packages/cli/generators/project/templates/README.md.ejs Outdated Show resolved Hide resolved

packages/cli/generators/project/templates/README.md.ejs Outdated Show resolved Hide resolved

dhmlau approved these changes Apr 3, 2020

View reviewed changes

packages/cli/generators/project/templates/README.md.ejs Outdated Show resolved Hide resolved

emonddr suggested changes Apr 6, 2020

View reviewed changes

feat(cli): set the template version to generate projects

fa6c107

Set version to 0.0.1

dhmlau assigned emonddr Apr 7, 2020

emonddr suggested changes Apr 7, 2020

View reviewed changes

packages/cli/generators/project/templates/README.md.ejs Show resolved Hide resolved

raymondfeng reviewed Apr 7, 2020

View reviewed changes

emonddr suggested changes Apr 7, 2020

View reviewed changes

packages/cli/generators/project/templates/README.md.ejs Outdated Show resolved Hide resolved

packages/cli/generators/project/templates/README.md.ejs Outdated Show resolved Hide resolved

feat(cli): customize README of project/extension template

9985492

dhmlau mentioned this pull request Apr 15, 2020

Documentation improvements 2020Q3 #5113

Closed

9 tasks

frbuceta closed this Nov 9, 2020

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[CLI] Improve readme of a new project #4981

[CLI] Improve readme of a new project #4981

frbuceta commented Mar 28, 2020

raymondfeng Mar 28, 2020

frbuceta Mar 28, 2020

raymondfeng Mar 28, 2020

frbuceta Mar 28, 2020

emonddr Apr 6, 2020

dhmlau left a comment

dhmlau left a comment

emonddr Apr 6, 2020

dhmlau commented Apr 7, 2020

emonddr commented Apr 7, 2020

emonddr commented Apr 7, 2020 •

edited

Loading

frbuceta commented Apr 7, 2020

frbuceta commented Apr 7, 2020

raymondfeng Apr 7, 2020

frbuceta Apr 7, 2020

raymondfeng commented Apr 7, 2020 •

edited

Loading

frbuceta commented Apr 7, 2020

raymondfeng commented Apr 7, 2020

frbuceta commented Apr 7, 2020

raymondfeng commented Apr 7, 2020

dhmlau commented Aug 19, 2020


		Refer to [Command-line interface](https://loopback.io/doc/en/lb4/Command-line-interface.html) for the full list of LoopBack 4 commands.

		### Adding Additional Dependencies

[CLI] Improve readme of a new project #4981

[CLI] Improve readme of a new project #4981

Conversation

frbuceta commented Mar 28, 2020

Checklist

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dhmlau left a comment

Choose a reason for hiding this comment

dhmlau left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

dhmlau commented Apr 7, 2020

emonddr commented Apr 7, 2020

emonddr commented Apr 7, 2020 • edited Loading

frbuceta commented Apr 7, 2020

frbuceta commented Apr 7, 2020

Choose a reason for hiding this comment

Choose a reason for hiding this comment

raymondfeng commented Apr 7, 2020 • edited Loading

frbuceta commented Apr 7, 2020

Getting Started

First Steps

Starting the application

raymondfeng commented Apr 7, 2020

frbuceta commented Apr 7, 2020

raymondfeng commented Apr 7, 2020

dhmlau commented Aug 19, 2020

emonddr commented Apr 7, 2020 •

edited

Loading

raymondfeng commented Apr 7, 2020 •

edited

Loading