Description for gulpfile

[segrey]

Now in gulp v4 it's possible to specify descriptions for tasks.
What do you think about ability to specify a short description for the whole gulpfile?
E.g. if this short description would contain a project name, it'd be convenient to see the project name when running the task (currently all gulpfiles are usually named the same for easier cli usage).
Looks like both tools (gulp-cli and IDEs) would benefit.

[phated]

Not sure how something like this would work. I really dislike adding APIs to the main gulp package/namespace to support display things.

[segrey]

Reluctance to extend API is understandable. Actually, the issue came from https://youtrack.jetbrains.com/issue/WEB-19115.
For instance, some other build tools allow to specify description, e.g. Ant
https://ant.apache.org/manual/using.html

<project name="MyProject" default="dist" basedir=".">
  <description>
    simple example build file
  </description>
  ...
</project>

I was thinking of exporting description via module.exports as a possible solution.

[yocontra]

Give the default task a description and use that?

[phated]

I think that's a decent compromise but I think people might already be using descriptions on default tasks (not sure).

[segrey]

Didn't think about it. Indeed, it's a good compromise. However, as a long-term solution, seems a task's description and a gulpfile's description have different goals. A task's description provides information about what this particular task does (likely, starting with a verb) and a gulpfile's description is just a common description of the gulpfile (likely, a project name).

Please feel free to close this issue if there are no plans to support this feature.

[brenmar]

Would be a hack, but I think it then compromises the semantic value of the description. Especially if the tasks then have their descriptions used in an IDE, say for instance if you had 'build debug version on localhost' as a description for the default 'build' task that would conflict with what you might want to name the file for instance 'my awesome project'.

Then in an IDE your gulpfile would either be labeled 'build debug version on localhost', semantically incorrect/confusing. Or it's labeled 'my awesome project', but your default 'build' task that 'build[s your] debug version on localhost' would then be called 'my awesome project' too. Which means that descriptions end up exhibiting less semantic value than original names, undermining the description concept.

You could have a dummy/empty default task and give it a description, but then that undermines the concept of a default task.

[phated]

@segrey we wouldn't be able to use module.exports because we now load tasks from that if they are exported (to support babel's export-to-commonjs transform).

[segrey]

@phated right, actually module.exports was not a great option because of mixing different styles (gulp.task(...) and module.exports). Maybe just gulp.description('My project') or something else.

[phated]

I really don't want to expose an API for this. Maybe if we get the .gulprc stuff wrapped up, we can put it as a property in there.

[phated]

Moved to gulpjs/gulp-cli#70 so I'll close this here.

[phated]

@segrey Great news! We will soon support custom top-level descriptions through the use of a .gulp.* file. Please review https://github.com/gulpjs/gulp-cli#configuration and let me know if that works for you. You will be able to read the description from the JSON object returned from --tasks-json as the top-level .label property.