Loopback-next: Consistent naming scheme for examples

[bajtos]

We need to come up with a naming scheme for our example repos and start following it consistently.

In the future (not for Beta), we may want to consider a monorepo (perhaps without lerna?) to keep all examples in a single place.

Acceptance criteria

• [x] Discuss with the team possible convention, come to an agreement about the one we want to use
• [x] Document the convention on wiki or in loopback.io contributors docs
• [x] Rename existing repos (~3-6 now) to match this convention
  ~- [ ] Make sure there is no reference of the old repo names~
  ~- [ ] Update the Tutorial&Examples doc: http://loopback.io/doc/en/lb4/Examples-and-tutorials.html~
  I haven't seen any other documents mentioned those examples other than Tutorial&Examples, and it doesn't make too much sense to change that page if we are refactoring all examples soon. So I deleted the last two ac.

And move them to the follow up story
https://github.com/strongloop/loopback-next/issues/645

[jannyHou]

A summary of our discussion on slack:

Plan 1: loopback-next-example-{foo}

From @bajtos :

For short-term (Beta), I would personally go for loopback-next-example-{foo} to stay consistent with the naming scheme we are using for loopback-example-{foo}, which is {project}-example-{example-name}

Concern about long-term naming conversion:

I am proposing to consider this in a broader context. The monorepo is called strongloop/loopback-next now, are we going to rename it to strongloop/loopback at some point? What will happen to the current strongloop/loopback repo with LB 3.x sources? Similarly, what is going to happen to exiting examples for LB 3.x, which are usually called loopback-example-{foo}?

Plan 2: loopback-{version#}-example-{foo}

From the discussion I think this is a plan eventually everyone likes.

• move all of the existing repos to loopback-3-example-{foo}
  
  
  
  • > would be an overkill at this point, too much documentation changes
  
  
• loopback-2-example-{foo}
  
  
  
  • we don't care about LB2 examples anymore
  
  
• when we have LB5, the loopback-4-example-{foo} might still be applicable. how can we make known to ppl?
  
  
  
  • If the example is exactly the same, then we'll just redirect loopback-5-example-* to loopback-4-example-*
  
  

[jannyHou]

example repos to rename:

• [ ] https://github.com/strongloop/loopback-next-example
• [ ] https://github.com/strongloop/loopback-next-hello-world
• [ ] https://github.com/strongloop/chit-chat (optional :-p)
• [ ] https://github.com/strongloop/lb4-log-extension-example
• [ ] https://github.com/strongloop/loopback-next-extension-starter
• [ ] https://github.com/strongloop/loopback-next-sandbox

Feel free to add it if I miss anyone, thanks!

[jannyHou]

Before figure out how to migrate contribution docs from https://github.com/strongloop/loopback-next/wiki/Contributing to loopback.io, I post the instruction here so people can discuss&give feedback:

## Naming Convention

### Example Repositories

When you create an example repository for any usage demo, the name of repository should follow the following convention:

`loopback-{major_version}-example-{example_name}`

Usually the `{major_version}` is the lastet major version under development.
If the example aims at a specific version of LoopBack, then use that number as the `{major_version}`.
The `{example_name}` is a few words briefly describes the functionality of the example,
and joined with dash `-`.

For example, we build a quick start example app for LoopBack 4 and name it as 
[`loopback-4-example-hello-world`](https://github.com/strongloop/loopback-next-hello-world).

[virkt25]

I think that format makes repo names unnecessarily long ... I’d suggest something like

• lb4-${projectName}-example
  Or projectName and example can be switched.

So what’s his would give us:

• lb4-hello-world-example
• lb4-log-extension-example
• lb4-hello-world-starter (I don’t think this is an example repo).

[jannyHou]

Thanks @virkt25 good point on keeping name short, I prefer to use the complete spell of loopback for the search purpose, e.g. a new user is interested in an authentication example, they may search
loopback authentication example, a full name matches better than an abbreviation.

But I feel loopback4-example-hello-world does look better than breaking it into 2 words.

[b-admike]

I like the idea and up for a shorter name as well. @jannyHou I think we can have keywords in the repos' package.json files where we can put loopback in, but if it does indeed improve search by a good amount by having it in the name, then I'm all for it.

[jannyHou]

@b-admike I might wrong about the search, not an expert of SEO :-p if it doesn't matter then lb{major_version} looks good.

[raymondfeng]

loopback4-example-hello-world LGTM.

[jannyHou]

seems loopback{major_version}-example-{example_name} is good. Any opinions or objections? If not we can move forward to rename existing ones :)

[dhmlau]

@jannyHou , I've added 2 more repos in your list:
https://github.com/strongloop/loopback-next-extension-starter
https://github.com/strongloop/loopback-next-sandbox

I believe the extension-starter is also an example repo?
@virkt25 ^^

[dhmlau]

Working with @jannyHou...

The following repos will follow the loopback{major_version}-example-{example_name} convention because they are examples.
https://github.com/strongloop/loopback-next-example
https://github.com/strongloop/loopback-next-hello-world
https://github.com/strongloop/lb4-log-extension-example

The following repos will loopback{major-version}-*: loopback-next-* -> loopback4-*
https://github.com/strongloop/loopback-next-extension-starter
https://github.com/strongloop/loopback-next-sandbox

[jannyHou]

A quick summary of extension repos:

was talking with @dhmlau, based on my understanding loopback-next-extension-starter is more like a template or sandbox, which waits for people to implement their functionalities, but itself doesn't demo any functionality, so it doesn't follow example repo's convention.

[virkt25]

Extension-starter is a template repo and not an example repo indeed but the templates contain basic extensions to demo a working template a user can modify.

My only suggestion would be can we consider putting the type last ... type being words like example or starter? I think that reads slightly better.

[dhmlau]

IMHO, I think type (example | starter) might be better to go first, i.e. loopback{major-version}-{type}-name. Not sure about starters, but for examples, it would be easier for people to find by loopback-example-

[jannyHou]

I would also like to use the pattern loopback4-example-{foo} since:

• This is the name we used in LB1-3
• When the example name turns to be multiple word, e.g. loopback4-foo-bar-baz-example, moving example before them(would be loopback4-example-foo-bar-baz) is more straight forward for telling the nature of this repo is an example.

Any other options on it?

[virkt25]

I’m ok with it. Makes sense to know it’s an example/starter repo before knowing the example.

[jannyHou]

Thanks everyone, @dhmlau now the naming convention is done:
loopback{major_version}-example-{example_name}

While after the meeting with Ritchie, we still need discussion on the {example name}
After we decide each example's real functionality, could you help on rename them according to https://github.com/strongloop/loopback-next/issues/614#issuecomment-334825003? Thanks! I think I don't have the permission to do a rename.

[jannyHou]

According to our discussion above and on Friday's meeting, I have a proposal to rename them as

https://github.com/strongloop/loopback-next-example --> loopback4-example-persistence-services
https://github.com/strongloop/loopback-next-hello-world --> loopback4-example-getting-started
https://github.com/strongloop/lb4-log-extension-example --> loopback4-example-log-extension

@here any thought or other better plan?

[raymondfeng]

https://github.com/strongloop/loopback-next-hello-world --> loopback4-example-getting-started

We probably want to break the current version into two examples:

1. A simpler loopback4-example-helloworld with only sequence/action to print out hello world!. No controllers or repositories are involved.

2. Rename the current repo to loopback4-example-getting-started.

[virkt25]

• For loopback4-example-helloworld shouldn't it be hello-world?

• I think it might also be worthwhile to have a hello-world-controller version which uses a controller to create a hello world response ... since that's more likely how a real user will be using LB4 (creating API's which vary based on a route vs. modifying sequence to return only 1 response). Something like below ...

app.controller(HelloCtrl);

class HelloCtrl {
  @get('/')
  helloWorld() {
    return 'hello world'
  }
}

[jannyHou]

@raymondfeng @virkt25 If there are two ways to demo "hello world":

• print it out by defining sequence
• define a route to print it from endpoint

Maybe we can use different branches in the same repo? They both look good to me.

And I summarized the examples we have in the following table with plans we can discuss and carry out afterwards:

| repo name | topic/tutorial | description | plan |
|-----------------------------------------|----------------|----------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| loopback4-example-hello-world | tutorial | uses sequence/action to print out hello world!. No controllers or repositories are involved. | easy to build, we can create a new repo |
| loopback4-example-hello-world-controller | tutorial | uses a controller to create a hello world response | easy to build, we can create a new repo |
| loopback4-example-getting-started | tutorial | builds an simple app with LoopBack4 key concepts | rename existing loopback-next-hello-world. I am not very familiar with it, we can discuss what concepts are missing in it and how to write the document to guide users with this example |
| loopback4-example-todo-legacy | topic | builds a todo app with legacy juggler | create a new repo, extract the app in folder /services/todo-legacy from loopback-next-example |
| loopback4-example-bank | tutorial | builds a bank app demo multiple repositories, relations, authentication feature. | rename loopback-next-example, extract other folders from loopback-next-example, refactor them according to the latest lbn |
| loopback4-example-log-extension | topic | builds an app demo a log extension | rename lb4-log-extension-example would be good enough |

[virkt25]

I don't think hello-world should have branches for sequence / controller because someone should be able to clone and run with master and not have to switch branches (think it keeps the developer experience cleaner). I'd say it should be different repos.

[raymondfeng]

-1 to use branches. It's not very friendly.

[jannyHou]

@virkt25 @raymondfeng ok then let's make two repos :)

[jannyHou]

@here feedback applied, see the new table: https://github.com/strongloop/loopback-next/issues/614#issuecomment-335839299
any thought?

[dhmlau]

LGTM!
The description for loopback4-example-getting-started might need some rewording, because it's not clear to me what key concepts i'll use if i follow this tutorial.

builds an simple app with LoopBack4 key concepts

I've also added the acceptance criteria to include updating the content in here:
http://loopback.io/doc/en/lb4/Examples-and-tutorials.html
Feel free to create a separate issue for this if you find it's more appropriate.

[virkt25]

Looks great. Agree with @dhmlau in that I think getting-started should probably be re-written to be a step-by-step (or branch-by-branch) tutorial for best practices & concepts for LB4.

Also missing extension-starter which I assume will become loopback4-starter-extensions or loopback4-starter-hello-extensions

[jannyHou]

Thanks everyone, let's continue the example discussion in https://github.com/strongloop/loopback-next/issues/645

Close it.