Details
-
Enhancement
-
Resolution: Done
-
Optional
-
2.x Future
Description
I was talking about having CLI naming conventions on the forum and George and Lincoln suggested to add these ideas on a JIRA. So here is my humble contribution to record all the ideas about renaming commands.
Disclaimer : I haven't used Forge for a long time, I've just started using it again, so some of the following ideas might not be accurate
As a new comer in Forge I felt the commands were not that intuitive. I loved the following :
java new-enum-type java new-itnerface java new-class
So I was expecting to have something similar in all the other techologies, such as JPA :
jpa new-entity (instead of entity --named) jpa new-embedable jpa new-mapped-superclass --named Person jpa new-entity --named Vet --extends Person
Lincoln suggested having single-level command keywords only such as :
jpa-new-entity (instead of entity --named) jpa-new-embedable jpa-new-mapped-superclass --named Person jpa-new-entity --named Vet --extends Person
Verbs and keywords
When you look at the commansd, there are several common verbs and keywords than come often :
add : ejb-add-transaction-attribute new : beans-new-bean, faces-new-view, new-project (prefer project-new) list : list-web-resources, beans list-interceptors, beans list-alternatives, list-scaffold-providers setup : ejb setup, entity setup put : i18n put remove : i18n remove, project remove-property execute : execute-java set : maven set-groupid find : forge find-plugin install : update : forge update-abort, gitignore update-repo run : run-url info : analytics info
That brings several thoughts :
- ls is used as well as list, should this be homogenize (e.g. beans-ls-interceptors)
- rm is used as well as remove, should this be homogenize (e.g. i18n-rm, project-rm-property)
- The difference between execute and run is not clear, should this be homogenize and only use one ?
- Also there is execute and exec, this should be homogenize (e.g. execute-java and exec)
- Confusion between new and add. You create a new class with java-new-class and shouldn't you add a field and a method to existing class (java-add-field instead of java-new-field)
- Some confusion between maven and project
- Is there any difference between set and update ? maven set-artifactid updates the already existing artifactId and gitignore update-repo updates an existing repo
- we use field (e.g. java-add-field) and then property (constraint Future --onProperty date), it should be fiels (constraint Future --onField date)
In many commands you find a type argument such as (type, scaffoldType, fieldType :
scaffold setup --scaffoldType faces field manyToMany --named specialties --fieldType ~.model.Specialty.java field temporal --type DATE --named date
Why not having only type in all the cases :
scaffold-setup --type faces jpa-add-field manyToMany --named specialties --type ~.model.Specialty.java jpa-add-field temporal --named date --type DATE
Grammar
The CLI grammar could look like this :
command = shell | forge command ;
forge command = technology,-action,[-artifact] [{--argument value}] ;
shell = cat | cd | cp | edit | find | grep | ls ...
technology = project | scaffold | beans | constraint | java | jpa | i18n | ejb ...
action = add | new | ls | rm | setup ...
artifact = providers | interceptors | class | filter...
argument = named | onField | type | extends
Examples
So if we take that grammar and apply single-level command keywords, we could have things like that :
mkdir ls ls-commands -all project-new --named MyPro scaffold-ls-providers scaffold-templates --scaffoldType faces beans-ls-interceptors constraint-new-constraint --named MyConstraint constraint-add-constraint MyConstraint --onField MyProp java-new-class --named MyClass java-add-field 'private List<Vet> vets' java-add-method 'public List<Vet> getVetList() {return null;}' java-add-annotation --type XmlRootElement --onClass MyClass java-add-annotation --type XmlAttribute --onField MyProp jpa-new-mapped-superclass --named Person jpa-new-entity --named Vet --extends Person jpa-add-field manyToOne --named owner --type ~.model.Owner.java i18n-add-locale --locale PT ejb-new-stateless --named MyStateless ejb-new-singleton --named MySingleton --implements MyInterface AndAnotherInterface ejb-add-transaction-attribute --type NEVER ejb-add-transaction-attribute --type NEVER --onMethod MyNeverMethod faces-new-view --named MyView faces-set-project-stage --stage PRODUCTION servlet-new-filter --named MyFilter rest-new-endpoint --named MyEndpoint --extends MyRestExtension mvn-build --notest
Scaffolding is a bit tricky because it's extendable and you could end up with
scaffold-ui-from-entity ~.model.* scaffold-rest-endpoint-from-entity ~.model.* scaffold-dao-from-entity ~.model.* scaffold-ejb-service-from-dao ~.dao.* scaffold-rest-endpoint-from-dao ~.dao.*
Or something like that
scaffold --ui --from-entity ~.model.* scaffold --rest-endpoint --from-entity ~.model.* scaffold --dao --from-entity ~.model.* scaffold --ejb-service --from-dao ~.dao.* scaffold --rest-endpoint --from-dao ~.dao.*
Here are my 2 cents thoughts on a topic that I'm discovering. As you all know, naming is really important and should be looked at carefully. Let's use this JIRA to exchange ideas.
Attachments
Issue Links
- is related to
-
FORGE-2128 Establish CLI guidelines for Forge 3
-
- Closed
-
-
FORGE-1320 Perform a UX review of the Shell experience in Forge 2
-
- Closed
-
-
-
- Closed
-
-
-
- Closed
-
- relates to
-
FORGE-1328 Rename addon commands
-
- Closed
-
-
-
- Closed
-
-
-
- Closed
-
-
-
- Closed
-
-
-
- Closed
-
-
-
- Closed
-
