Stabilise the package API

[jaxxstorm]

I have a use case I'd like to have considered.

I'm building an internal application which will:

• Traverse through a directory hierarchy and fine all Taskfile.yml instances
• Run the equivalent of task -d <dir>/Taskfile.yml on all those taskfiles concurrently

As pointed out in slack, I can use os/exec for this, but ideally I want to be able to just import github.com/go-task/task and then use those functions/methods from there. This will ensure that user's don't need to download a binary to run the internal tool

Would this be something that might be considered?

[smyrman]

While task is a great CLI tool, my personal opinion is that the underlying code may not be among the cleanest, and not all packages has the right separation of public vs private members. I should add as a disclaimer that there is some time since I last looked at the code base.

Still, I think the best approach for this issue may be to first suggest/dream up a good spec for how a minimal public interface should look like, and then those public functions can either be reimplemented or call code living in packages under the internal namespace to get the job done, which ever is easiest in each case.

Basically hide away most of the code under internal/ (or make things private within each particular package) to allow for refactoring intenally, while keeping a clean, minimal and backwards-compatible public interface.

[smyrman]

PS! I think that the code base has changed significantly since my last contribution, so a lot of code does already live in the internal/ packages.

[andreynering]

@smyrman Yes, I have been trying to refactor things step-by-step, specially splitting code to packages and declaring interfaces to abstract code

I agree that once we declare the use as a lib as "officially supported" we should worry about backwards compatibility

@jaxxstorm By now, if you don't want to wait, feel free to open a pull request moving the args and taskfile packages from internal/ to the root directory. I think that will be enough to allow you doing what you need. That said, I suggest you to keep this lib in the vendor/ directory for now

Agree that stabilising the API is a good idea.

I think worrying about not breaking people in the future is fools gold. Hey ? It's a tool not an APP delivered over Google play with a server using grpc that needs to support Schema Evolution. Being a tool means yes breaking the API.
Instead support a version tag at the top and then have public API's that are for each version.
That's probably easily good enough.
But also that's slot of work to support. So when you get down to the fact that it's a tool and a go get -u will get you to the latest then maybe that's ok.

I just worry that stable API / schema is too much work

Then I think about how Mage supports plugins. It allows me to build a version of task that I need for my users. Break my plugins instead is better and let me insulate my users from change.
In fact that is exactly how I am using Task now. I have Mage with its various plugins. I compile it, and then I wrap it with Task so users have a awesome cli that is actually an interpreter on top so that can customise the variables and little extra things they need to do.

[damian-szulc]

@andreynering what's the status and plan to tackle this? I'm interested in using taskfiles as an external library. I'd like to be able to programmatically list and run available tasks. Is there anything I can do to help?

[andreynering]

The args and taskfile packages were now moved from the internal dir to the root of the repo.

This will allow people to run Taskfiles programatically. Consider this to be unstable for now, though. No backward compatibility guaranteed.

[chinglinwen]

I've try run cmd/task/task.go in different repo for test, Somehow it says does not contain package args and taskfile. @andreynering

go: finding module for package github.com/go-task/task/v3/args
go: finding module for package github.com/go-task/task/v3/taskfile
task.go:13:2: module github.com/go-task/task/v3@latest found (v3.0.0), but does not contain package github.com/go-task/task/v3/args
task.go:16:2: module github.com/go-task/task/v3@latest found (v3.0.0), but does not contain package github.com/go-task/task/v3/taskfile