Records and suggestions from the development of v0.2

[kdada]

This issue is for recording the rest works from the development of v0.2.

@ddysher

• Add a README.md file with short introductions about the generated project (the purpose of this readme file is to guide users to create their own README file)
• Add docs.go for each package
• How to handle pkg/database
• glog exits with 255, C/C++ uses -1, which ended up with 255 also
• Auto this method hard-code quite a few things, which are actually user-facing (part of the framework API)?
• I'm a little concerned about using init() to register handlers, is there a better alternative?
• why do you redefine everything here again?.... this is not maintainable
• are u sure these are the right things to do....
• Also, i suggest we can make /path/to/apis optional in nirvana api (set the default to pkg/api as we already have a recommended structure.
• PS. let's change pkg/api to pkg/apis, since we mostly always have more than 1 API in a project :)
• I'll send a patch to update README template shortly.

@caitong93

• It is better to split out these templates to dedicated files for better management. Also we should provide a way to customize the default templates.

@zjj2wry

• add default value to &apiOptions{}, It's easier to add unit tests
• init should top of api command in help.
• nirvana init should be have some prompt when init success.
• would be better hava log like kubectl get node -v 10 in REST.
• If you do not specify args, you should use the default path, I think you can add a line of log to tell the user.
• Since it will use the first configuration that can be read, I think it is possible to limit the length of args to not greater than 1.
• would be better print what dir you read.

Related PRs:
#209
#211
#212

[kdada]

Add a README.md file with short introductions about the generated project (the purpose of this readme file is to guide users to create their own README file)

Added

Add docs.go for each package

For api servers, doc.go may be not useful. In most scenarios, we don't add a separated file to write docs.

How to handle pkg/database

pkg/database is an irrelevant part with nirvana. We can regard it as a best practice and put it into manuals.

glog exits with 255, C/C++ uses -1, which ended up with 255 also

I just followed golang log package.

Auto this method hard-code quite a few things, which are actually user-facing (part of the framework API)?

I have already recorded it into manuals.

I'm a little concerned about using init() to register handlers, is there a better alternative?

I think init() is a better way than others. In a go file, init only register APIs which are in current file. That means we don't impact other files when we want to add/modify/delete APIs in a file.

why do you redefine everything here again?.... this is not maintainable

The two structs are not completely same. The struct in utils/api contains more fields than the corresponded one in definition (Also some fields are different). We may consider about how to merge them in the future.

are u sure these are the right things to do....

Yes. Ignore some checks in gometalinter for using unsafe package.

Also, i suggest we can make /path/to/apis optional in nirvana api (set the default to pkg/api as we already have a recommended structure.

It's reasonable.

PS. let's change pkg/api to pkg/apis, since we mostly always have more than 1 API in a project :)

It's reasonable.

I'll send a patch to update README template shortly.

OK.

SUMMARY

1. Add best practice about pkg/database into manuals.
2. Add best practice about client generation into manuals
3. Add default path to nirvana api
4. Rename pkg/api to pkg/apis
5. Refine README.md from nirvana init

@ddysher WDYT?

[kdada]

It is better to split out these templates to dedicated files for better management. Also we should provide a way to customize the default templates.

It's reasonable but not urgent.

@caitong93 you can refactor it if you are free.

[kdada]

add default value to &apiOptions{}, It's easier to add unit tests

Default values for apiOptions can't make you easy to add unit tests. Because you always need to construct a test project.

init should top of api command in help.

It's default order of cobra. If you thinks it's not Intuitive, you can create a pr to fix it.

nirvana init should be have some prompt when init success.

It's reasonable.

would be better hava log like kubectl get node -v 10 in REST.

rest package supports RequestExecutor. you can write log by yourself.

If you do not specify args, you should use the default path, I think you can add a line of log to tell the user.

Same as

Also, i suggest we can make /path/to/apis optional in nirvana api (set the default to pkg/api as we already have a recommended structure.

Since it will use the first configuration that can be read, I think it is possible to limit the length of args to not greater than 1.

No. In most cases, one arg for path is enough. But sometimes, our descriptors and modifiers may be in different directories. So we need support multiple args.

would be better print what dir you read.

It's reasonable.

** SUMMARY **

1. Add success message for commands
2. Print more useful messages when a command is running

@zjj2wry WDYT?

[kdada]

Backlogs:

1. [P0] Add default path to nirvana api feat(cmd): move /pkg/api to /pkg/apis #221
2. [P0] Rename pkg/api to pkg/apis feat(cmd): move /pkg/api to /pkg/apis #221
3. [P0] Remove contention from profiling fix(profiling): remove contention #223
4. [P0] Add handlers for uploading/downloading static files feat(service): add helper functions to support static file server #222
5. [P0] Support interface in client generation. fix(golang): support to generate io.Reader and io.ReadCloser #224
6. [P1] Add best practice about client generation to manuals feat(manuals): add manuals of plugins and clientset #226
7. [P1] Add success message for commands feat(cmd): move /pkg/api to /pkg/apis #221
8. [P1] Print more useful messages when a command is running feat(cmd): move /pkg/api to /pkg/apis #221
9. [P2] Refine README.md from nirvana init @ddysher
10. [P2] Add best practice about pkg/database to manuals.
11. [P2] Add more details to manuals

[kdada]

PR has been merged. And we can track the doc by #227.