Recommendations for Sharing Workflows

[jdfwarrior]

Recommendations for Sharing Workflows

 

The forums have really been running well and you guys (and gals) have been creating some amazing workflows so far. I wanted to throw out a few suggestions though to make sure things stay organized, are easy to read, and easy to find.

 

This will be an evolving document. Check back for questions regarding questions on posting your workflows. If you have a question that isn't answered within the contents of this thread, feel free to contact any of the moderators (Myself, Andrew, or Vero). 

 

Post Titles

Be specific. Don't be overly descriptive about every little feature the workflow provides. Titles are best kept to the workflow name, and potentially a few words on the overall gist of what it does.

 

Tags

Be sure to set topic tags for your workflow post. This will make it easier for users searching on the forums to find your post/workflow easily based off of a few key words.

 

Dependencies

Please include a listing of all dependencies for your workflow. This will hopefully alleviate potential problems that users run into from attempting to run an installed workflow without an installed package being present. Examples of this would be Ruby gems or Python modules or even Python versions that are required for using the workflow. If a specific application is required for your workflow to function, be sure to include a link to that applications website, or a link to it in the App Store as well. Also include, if necessary, required versions of OS X.

 

System Modifications

If your workflow creates or modifies any supporting files that would alter the users environment, this should be noted. This will make it known up front that your workflow modifies system file X to achieve its functionality. Also, if the user uninstalls the workflow, how to remove these files or restore the originals.

 

Screenshots

They aren't required, but providing a screenshot or two for your workflow helps provide users with a good idea of what it is they are about to download. Descriptions help, but many users are wanting to pop in, get a quick visual, and download.

 

Posting

When sharing a new workflow, please be sure to create your own thread for it. By posting it in another workflows thread, your workflow may never reach the masses. Create your own thread so that it stands out and everyone will be able to find it easily. This helps remove confusion on which workflow to download if there are multiple workflows, or modified workflows posted within the same thread. It also helps ensure that the develop that spent their time and put in the hard work to create the workflow get credit for their work. Posting a patch/update/fix/modified version of a workflow in another authors thread may steal attention from their original work. So let's try to be considerate.

 

Sharing Multiple Workflows

Try to limit a new thread to a single workflow. The reason for this follows the situation mentioned above. Unless you have an abnormally long title, users casually browsing the forums may not realize how many workflows are available in the post, or what they are. Creating a separate post for workflows also creates an individual area for you to provide support or answer questions for that workflow alone.

 

Modifying Existing Workflows

Most developers are very open to feature requests for their published workflows. So before modifying someone else's workflows, check with the developer and see if they would add the feature first. If the requested feature is something that the developer doesn't plan on adding, of course you could add the feature yourself. If you think it's a feature that others would also find greatly useful and you decide that you would like to share your modified version, please be respectful of the original developer give them a heads up before hand. Also, be courteous and give credit to the original author and/or a link back to their original thread so that they receive some credit for their work. Nobody enjoys having their work stolen.

 

Updating You Workflows

When sharing an update to an already posted workflow, rather than creating another post in the existing thread, update the initial post to include desired information and updated download links (if necessary). This makes it easier for users to find the most up to date version of your workflows, along with information what is included in the update. You could also modify the thread title to indicate the date that the workflow was last updated.

 

 

Notice: I'm also going to try to monitor this thread and keep it clean. If you post suggestions for other things to be added to the document, if they are merged in, I will probably remove your original post. Questions will also be treated the same way. If answers are later added into the original post, I may remove the original question. This will hopefully keep it so that all documentation remains in the original post so someone doesn't potentially have to search through several pages of questions for find a simple answer.

[poritsky]

Awesome overview of workflow etiquette. Two questions come to mind:

1. Should download links go directly to the download or to the download page. I've been using direct download page so dl starts in one-click. If this is uncool (uncouth?) I'll stop.
2. I've been using myname.workflowname (e.g. poritsky.appzapper) for bundle ID. Is there a preferred format otherwise?

[hzlzh]

Many developers use Dropbox links, but some days later, the file gone and the link broken.

[CarlosNZ]

Updating You Workflows

When sharing an update to an already posted workflow, rather than creating another post in the existing thread, update the initial post to include desired information and updated download links (if necessary). This makes it easier for users to find the most up to date version of your workflows, along with information what is included in the update. You could also modify the thread title to indicate the date that the workflow was last updated.

I've wondered about this. I've always tended to post at the end of the thread as well as updating the original post just so those that are "following" the thread get a notification that there is an update. I don't suppose just editing the first post is enough to trigger a notification from the forum, is it?

[jdfwarrior]

Awesome overview of workflow etiquette. Two questions come to mind:

1. Should download links go directly to the download or to the download page. I've been using direct download page so dl starts in one-click. If this is uncool (uncouth?) I'll stop.
2. I've been using myname.workflowname (e.g. poritsky.appzapper) for bundle ID. Is there a preferred format otherwise?

 

1. Most people would probably prefer linking directly to the workflow but I personally don't do this. I link all of mine back to my blog currently so I don't have to change the download link on my blog and on the forums every time something gets changed. I just leave the forum post as a link directly to the blog post.

2. We haven't set a preferred format for the bundle id yet, just make sure that it will be something unique. This bundle id will be used to identify the workflow when installing updates to it. 

 

I've wondered about this. I've always tended to post at the end of the thread as well as updating the original post just so those that are "following" the thread get a notification that there is an update. I don't suppose just editing the first post is enough to trigger a notification from the forum, is it?

 

Perhaps not. If you still want to create a new post at the bottom, that would be fine. It's just recommended that you keep the download link at the top. It makes it a lot easier to find. That was the main thing to note under this topic. If you make an update and post it, then 15 people comment on it before I find my way to it, then I would have to search through the thread to find the actual download link as opposed to it just easily being available at the beginning. Make sense?

[vinh291]

Is there some kind of giant list that new users could pick and choose from? I find it a hassle to go through the forum finding what you want.

 

A dedicated website or blog with requests built in would be cool.

Edited March 24, 2013 by vinh291

[Carlos-Sz]

Maybe we could have a forum only for Workflow Requests and let Share your Workflows for workflow releases only and Workflow Help & Questions for users trying to make their own workflows.

[jdfwarrior]

Maybe we could have a forum only for Workflow Requests and let Share your Workflows for workflow releases only and Workflow Help & Questions for users trying to make their own workflows.

 

That has somewhat formed on its own already. There aren't too many requests that show up in the Share area. Many show up in the Questions area already.

[perldork]

Something like rubygems.org for Alfred would be terrific - if that were created we would get

* Ability to search for workflows to add from the community *from* Alfred, similar to how add-on management works in Textmate or Sublime Text 2.

*Ability to publish (create or update) a work flow from Alfred to the yet-to-be-created central repository .

 

These features would make it easy for anyone with Alfred to manage add-ons, update, etc ... could even be a Powerpack feature if cost is an issue.

[Mijathi]

I really hoped the workflow process would be less a mess, but it seems it isn' t. 

No version management, no update feature. I agree with perldork, a central repo could already help out.

 

I' m also a little puzzeled with this:

 

 

Dependencies

Please include a listing of all dependencies for your workflow. This will hopefully alleviate potential problems that users run into from attempting to run an installed workflow without an installed package being present. Examples of this would be Ruby gems or Python modules or even Python versions that are required for using the workflow. If a specific application is required for your workflow to function, be sure to include a link to that applications website, or a link to it in the App Store as well. Also include, if necessary, required versions of OS X.

 

 

A few weeks ago I opened a thread to ask if groovy support would be a possibility and it was not considered because there was a dependency with a groovy runtime... . 

[vitor]

Is there some kind of giant list that new users could pick and choose from? I find it a hassle to go through the forum finding what you want.

 

A dedicated website or blog with requests built in would be cool.

 

Unofficially, yes, there’s something like that.

 

Something like rubygems.org for Alfred would be terrific - if that were created we would get

* Ability to search for workflows to add from the community *from* Alfred, similar to how add-on management works in Textmate or Sublime Text 2.

*Ability to publish (create or update) a work flow from Alfred to the yet-to-be-created central repository .

 

These features would make it easy for anyone with Alfred to manage add-ons, update, etc ... could even be a Powerpack feature if cost is an issue.

 

Well, workflows themselves are powerpack‐only anyway, so there’s really no reason to have that as a free feature.

[rice.shawn]

Other ways are in development.

 

(edit: see Packal)

Edited September 30, 2014 by Shawn Rice

[jdfwarrior]

I really hoped the workflow process would be less a mess, but it seems it isn' t. 

No version management, no update feature. I agree with perldork, a central repo could already help out.

 

I' m also a little puzzeled with this:

 

 

 

 

A few weeks ago I opened a thread to ask if groovy support would be a possibility and it was not considered because there was a dependency with a groovy runtime... . 

 

Andrew has many ideas and plans for enhancing and improving workflows.

 

As for the dependencies, if I remember correctly, you were asking for Groovy be offered as one of the language selections and I said that so far we were only providing support for languages that came with the default OSX installation. That doesn't mean that Groovy or other languages don't work. The only way they differ from the ones in the default list would be that you need to specify the path to the binary file. So, in this case, it would be that Groovy should work as long as you specify the full path to the binary but if you decide to distribute a workflow created with Groovy that you should list it as a dependency. Otherwise, users are going to download and install it and it's not going to work.

[deanishe]

Not sure if this is quite the right thread, but if you're distributing a workflow written in Python, *do not* ask users to install Python libraries in the system Python. Bundle them with your workflow.

It's not ideal, but installing libraries into the system Python is very bad form. The chances are good that you'll break some other software doing the same naughty thing—or it will break your workflow—by installing an incompatible version of a library.

It's trivial to install libraries directly in your workflow with "pip install --target=my/workflow/dir". Do that instead.

In addition, bundling the libraries with your workflow means the workflow will sync across machines without problems.

[rice.shawn]

Not sure if this is quite the right thread, but if you're distributing a workflow written in Python, *do not* ask users to install Python libraries in the system Python. Bundle them with your workflow.

It's not ideal, but installing libraries into the system Python is very bad form. The chances are good that you'll break some other software doing the same naughty thing—or it will break your workflow—by installing an incompatible version of a library.

It's trivial to install libraries directly in your workflow with "pip install --target=my/workflow/dir". Do that instead.

In addition, bundling the libraries with your workflow means the workflow will sync across machines without problems.

 

I agree entirely (obviously), but it's also good to note that `pip` is not native on OS X. easy_install is but not pip. Blame Apple for that.

[deanishe]

Could somebody more familiar with Ruby explain how to bundle gems with your workflow?

 

As with Python, asking users to install gems in the system Ruby is a recipe for disaster.

[vitor]

To install

gem install --install-dir "{{custom_dir}}" --no-ri --no-rdoc "{{gem}}"

To load from bash

So you can simply ‘require’ in ruby

export GEM_PATH="{{custom_dir}}"

To load from ruby

Follow with ‘require’ as usual

$LOAD_PATH.unshift '{{custom_dir}}/gems/{{gem_dir}}/lib', '{{custom_dir}}/gems/{{other_gem_dir}}/lib'

[deanishe]

Sweet 

[rice.shawn]

Just steal the code from the ruby version of the bundler. It's all there and works.

[deanishe]

I don't want to do it. I just thought it should be in this thread. Perhaps on the wiki, too.

[stefano]

Can anyone  explain how to setup github in oreder to share the workflow code?

is there a template for the structure or a common structure that one should follow?

Edited September 30, 2021 by stefano

[deanishe]

There's not really a standard. You can just make the workflow folder a repo and upload that to GitHub. Or you can have the workflow in a subdirectory if there are other files you want to include in the repo, but not the workflow.

 

The main thing is to upload the expanded workflow, not (just) the zipped exported version.