chocolatey / docs

https://docs.chocolatey.org - new docs website
Apache License 2.0
155 stars 173 forks source link

Create official tag list and add to documentation #343

Open pauby opened 7 years ago

pauby commented 7 years ago

After a discussion in the Gitter channel around there being no list of tags I'm raising this issue for discussion around this before creating the docuimentation.

It's been suggested that the documentation be created on the Creating Packages page.

The list of tags I'm aware (off the top of my head):

List of tags I'd like to add:

* licensed - package requires a license to use - this is different from trial which still runs for a period of time; license tag is already recommended.

Also highlight that packages should not include the tag 'chocolatey'

Agreed Tags

The tags so far agreed on are:

Tags Under Discussion

Package category tags still under discussion:

Other tags still under discussion:

bcurran3 commented 7 years ago

My comments from here: https://groups.google.com/forum/#!topic/chocolatey/5Sw1CXMOrJk

I'm specifically interested (at the moment) about the subject of tags in packages. I can't really find much reference to it in the Chocolatey documentation other than basically they exist and to use them.

This is partly brought up by the Narrative Docs / Walkthroughs chocolatey/docs#342 discussion at https://github.com/chocolatey/choco/issues/1303.

I would like to recommend a standard tagging procedure.

I think all package tags should include: program name and/or acronym for such software company or developer's name (standard first initial last name format?) name of any dependency package(s) a standard classification (from a published list), i.e. productivity, programming, utility, browser, drivers, server, client, addon, etc., etc. silent or notsilent install or portable (maybe install assumed and portable required?) binary when a binary is included I think it should also be clearly defined when to use: notsilent admin trial (though it should be obvious) unofficial Hopefully the end result would be a lot more consistency, easier more productive searches, and less kick backs from moderators.

AdmiringWorm commented 7 years ago

I agree with having a standardized classification that needs to be used (kinda similiar to having a main group the software belongs to). I also agree with having the software name should be in th tags (especially when package name and software name differ). Not sure if I agree with having the software author in the tags though. Same thing with a binary tag, seems unneccessary.

pauby commented 7 years ago

I agree having the software name in the tags as long as the package name and the software differ. However we don't want to have too many tags or it's going to look a mess.

With regards to the @bcurran3 tags:

I think it should also be clearly defined when to use: notsilent admin trial (though it should be obvious) unofficial

That's why this is here! :)

AdmiringWorm commented 7 years ago

name of any dependency package(s) - what is there are 3, 4, 5 or 6? I think we need to keep the tags relevant and concise;

I somehow missed that one, I agree the tags should be kept relevant and concise. I see no reason to have a dependency mentioned in the tags, unless the package is a addon/plugin/extension of another program.

pauby commented 7 years ago

I am constantly mindful of the moderation guidelines for tags:

ferventcoder commented 7 years ago

This is a good discussion. I see no need to jump in currently.

bcurran3 commented 7 years ago

@pauby Since you're creating the documentation, could you link us to any existing documentation please? I just searched but can't find it. I know I've seen a small blurb on it somewhere, good to review it as a starting point.

I think the documentation should include:

Actually if it's officially stated now the purpose and use of tags in the Chocolatey ecosystem, I'm going to have a lot more comments and justifications. :)

pauby commented 7 years ago

There isn't what you're looking for AFAIK (hence the raising of this issue). There is some reference to tags in the [Moderation Guidelines[(https://chocolatey.org/docs/moderation) and in Creating Chocolatey Packages. I'm sure somebody else will jump in with more.

At the moment we have four tags that we've agreed on:

We also agreed on a productivity tag but I believe we should limit that to two. The productivity tags that have been mentioned are:

I think the ones in bold are quite vague and would rather have something a bit more specific. I think we should stick to a list of no more than a dozen to 15 of them. Any more and I believe it will get out of hand.

I also think that the total number of tags shoould not exceed 10 with 6 - 8 being ideal? I think a dozen is excessive.

But have said about the limits I wouldn't like to limit people. Bu I do think the limits I've suggested above give packagers plenty of scope.

bcurran3 commented 7 years ago

Do tags show up in Search Package results on the chocolatey.org website?

The answer to this significantly determines my stance on tags.

pauby commented 7 years ago

I believe that searching matches on the title, description and tags. @ferventcoder would be able to confirm exactly what is matched.

AdmiringWorm commented 7 years ago

I think it's only id and tags (or that's what I would expect anyhow)

pauby commented 7 years ago

I just did a search for PDF and Ghostscript came up - the only mention of PDF is in the description. Prior to that I thoguht it was title / package name and tags.

AdmiringWorm commented 7 years ago

I delved into the code a little bit, from the looks of it the default search uses id, summary and description, unless the search criteria is prefixed with either id:, author: or tag:

pauby commented 7 years ago

If you search for 'admin' (probably the most used tag) it returns 1908 packages. If you look at WinRar, the only place the word 'admin' appears is in the tags. So it must also search those.

AdmiringWorm commented 7 years ago

@pauby not according to the code: https://github.com/chocolatey/chocolatey.org/blob/master/nugetgallery/Website/Services/Extensions.cs#L26-L30 https://github.com/chocolatey/chocolatey.org/blob/master/nugetgallery/Website/Services/Extensions.cs#L61-L64

pauby commented 7 years ago

@AdmiringWorm I can only tell you what I see. There may be another simple explanation for what I see.

gep13 commented 7 years ago

@pauby @bcurran3 @AdmiringWorm in the search box, you can do something like the following:

tag:adobe

To search specifically only for tags that contain adode

AdmiringWorm commented 7 years ago

@gep13 that's kinda what I meant by

search criteria is prefixed with either id:, author: or tag:

pauby commented 7 years ago

@gep13 If you don't use the 'tag:' prefix, what does it search by default?

@AdmiringWorm My question is revolving around what the code says is different to what I experience, assuming what I experience is not explained by a simple ... explanation :)

gep13 commented 7 years ago

@pauby unless I am also missing something, I would say that the code that @AdmiringWorm linked to would be what is being used. What I am not clear on is whether the search goes across all the package versions for a package. i.e. Although WinRar doesn't currently have admin in it's id, summary, or description, if it had it in an older package version, would it still appear in the search results?

pauby commented 7 years ago

@gep13 That's what I was looking for - a simple explanation. I will try and find a package with only a couple of previous versions I can go through and come back. And maybe my inquistive mind will be satisfied :)

pauby commented 7 years ago

I just searched for 'admin' again and I've just gone through all the versions of Silverlight (there are only 6). Prior to the current version they didn't use the admin tag at all. None of the versions use 'admin' in the description, summary or title yet it still shows up in a search for 'admin'?

Can somebody else verify this?

pauby commented 7 years ago

I've also just noticed a package with teh following tag (whcih I've added to the first post so I can keep a track on them) - notUninstallable - a bit of a mouthful but maybe another tag we can consider?

bcurran3 commented 7 years ago

So what I'm seeing here is a few problems: 1> If the development team doesn't know how tags are used on the website, the end users aren't going to know! 2> Tags need to be defined as to why they are in a package and how they are useful afterwards; which needs to be part of the documentation. (Documentation telling/suggesting things should always cover "Why?" aspect of reasoning and when appropriate cover WIIFM - What's In It For Me?)

I learned something, I never noticed the pop up over the search icon on the website showing "Search by id only with 'id:searchValue'. Search by tags with 'tags:searchValue'.

To come full circle, tags should be looked at from the end user perspective. How are they useful to an end user? IMHO I believe the Chocolatey Team sees the website package search as a way to find what you're looking for. I believe tags should be an easy way to find software that you DO NOT know you're looking for. Standardized classification/grouping tags will help this a lot.

Even though Chocolatey in concept is far from file hosting websites such as FileHippo, MajorGeeks, etc. - the display of available packages should be as easy to find as they are to install. When I go to the Chocolatey.org website, I see the same 30 packages displayed displayed over and over and over again, for years. It's very boring. When I go to these other sites, I see what's new, I get lists of what's new and/or what's popular. This gets me excited to try out new programs. Choco development is on a nice fast release schedule, but the website needs a complete overhaul to include features such as what's new to rev up users and keep them excited about Chocolatey. Hell, it would draw more users and Chocolatey.org might be able to through some ads up for revenue (Try hitting up the shareware and trial vendors that already have packages available via Chocolatey - win win!) I know there is an RSS feed and I see it in my feedly now and then... but how about a sidebar on the Chocolatey.org landing page that scrolls that RSS feed so people know about new packages?

(I went a little off-track here, so this is a little jumbled and no good segway...)

The id:Adobe is a good example. By putting the dev in as a tag, you can easily find other programs by that dev. Sometimes I "discover" a new software company and really like a product, and I want to see if they have more good stuff. Let's take NirSoft as an example, if I search on Chocolatey.org for "nirsoft" it returns 12 results. I think all but one of them are NirSoft programs. But if I search "tag:nirsoft" I get 0 results. There are other instances when I search for something where I get 300+ results but if I could use tags to limit the search to the dev, I'd be able to find what I want without having to click next and load 20 more pages. There are no perfect examples of this because the tags aren't used consistently. But as a pseudo-good example if I search for "microsoft" I get 583 results but if I search "tag:microsoft" I only get 259 - helps a lot in finding that Microsoft program I'm looking for. I actually try to search by development house a lot when the program I am trying to find is described too generically causing a ton of noise hits.


Agreed Tags

The tags so far agreed on are:

admin trial notsilent license Tags Under Discussion

Package category tags still under discussion:

productivity programming utility browser drivers server client addon Other tags still under discussion:

notUninstallable

admin tag - I really hate this tag. I have it default in all my templates. To me it seems that MOST packages INSTALL a program and thus require admin privileges and the tag. I tend to think exception based (and am interrupt driven), so I think the tag is useless (running with the notion that tags are only good for searches) as anyone with admin rights on their computer isn't going to pay attention to it as it's meaningless to them. I think an opposite to admin tag is much more uself. Something like "noadmin" or "noadminrights" is much more useful to an end user who has Chocolatey installed on a locked down corporate machine. If I was such a user and found (made up scenario) Tetris available to download onto my machine and it didn't require admin rights for me to get and waste time.....I'd be looking for other programs that I could get that also didn't require admin rights - How would I search for that now? I don't think I could, but it would be nice if I could simply search "tag:noadminrights." Running with this example, if the program was written in Java, I might start searching for more programs written in Java and search for java. If runtimes/dependencies are required in tags, I'd easily be able to find more Java programs that I'd be able to run.

server tag - might need some definition or possibly two tags - Is it a program that only runs on server OSes? Or is it a server function program that could run on any Windows OS?

Honestly, I think we're trying to reinvent the wheel here. IMHO I think some research should be done by reviewing popular download sites and seeing how they use the tags as well as what popular tags they use. It's not about copying other people's ideas, it's about presenting the information to Chocolatey users in a format that they already know and expect.


dragonwolf83 commented 7 years ago

I think some concepts shouldn't be tags. It's very easy to abuse this concept where a better solution is to make more of the meta-data on software packages searchable instead of making it all "tags".

For example, software company and author are critical for searching as @bcurran3's use cases show. However, that is not a tag. That is distinct information that should be included in the meta-data and made available to search. Software Name, Package Name, Version, Last Update, Maintainers are all pieces of this meta-data.

One of the biggest problems for me is that I can't effectively search Software Name. I want to find all versions of SQL Server or Visual Studio and I get tons of stuff that is neither of those things. I try to cheat with tags but not all of them use the same tags nor should they. If I use tags for those things, I'm being redundant and wasting space for it. It devalues the usefulness of tags. Many parts of the meta-data is already there and just needs to be made searchable by that field alone. Then, if anything is missing in that meta-data that people are abusing tags for, could be made into a distinct field and made searchable as well.

Where tags are most useful is specifying multiple labels to something that can't be easily put into one category or definition. This works creates searchable "keywords" that you might want applied when one word doesn't do it justice. As someone who still puts application into a folder structure by category, I can tell you that it's hard to classify some apps by one category. Tags are a solution to that problem. It's usefulness though will only be as good as a developer/maintainer's ability to anticipate how their use base will think of their software. It might be something that needs to be done by the community, machine learning, or job.

bcurran3 commented 7 years ago

I can agree pretty much with @dragonwolf83 said.

I think a clear definition of the purpose and use of tags needs to be established as precedent before a decision on what tags to use is made.

If tags are only used by Chocolatey.org search and search can be made more granular without the use of tags, it seems tags might not be useful at all in most cases but necessary for some exceptions or basic categorization.

Tags use should be useful.

bcurran3 commented 7 years ago

notUninstallable - a bit of a mouthful but maybe another tag we can consider?

Another consideration: should tags be dictated as being lowercase only?

I realize that searches/search results should be case insensitive, but I can foresee the possibility of displaying a list of used tags, or tag cloud, where duplicates would be shown due to the same tags with differing upper/lowercase spellings - might be wise to prevent it right from the "start."

Let's make Chocolatey tags useful! (snicker)

ferventcoder commented 7 years ago

1> If the development team doesn't know how tags are used on the website, the end users aren't going to know!

The development team knows. Search by default is on id, title, description, tags (and maybe some other text field). There are weighting that go into this as well.

You use id:, etc to limit the search to just those fields.

ferventcoder commented 7 years ago

Chocolatey.org might be able to through some ads up for revenue

No. No ads. Ever.

ferventcoder commented 7 years ago

admin tag - I really hate this tag. [..snip...] I think an opposite to admin tag is much more uself. Something like "noadmin" or "noadminrights" is much more useful to an end user who has Chocolatey installed on a locked down corporate machine.

I actually think I agree with this more and more. I would much rather see a "portable" tag if the package doesn't have ".portable" as part of its name.

ferventcoder commented 7 years ago

So a vision for tags for me -

bcurran3 commented 7 years ago

I actually think I agree with this more and more. I would much rather see a "portable" tag if the package doesn't have ".portable" as part of its name.

This brings up the subject of consistent naming patterns. :) Off subject, I know. According to the documentation (https://github.com/chocolatey/choco/wiki/CreatePackages#naming-your-package) there really should be very few package names with a "." in them and much more with a "-" in them. Yet I see many many many ".install" and ".portable" packages instead of "-install" and "-portable" packages. (And yes I realize some of them have been around a long time and probably before some of the documentation was written and/or before moderation came into being. Maybe there should be a push to make older packages consistent with modern times and naming conventions. Maybe any package that didn't go through moderation should be asked to be updated so it can go through moderation.)

IMHO: The majority of programs have an installer. ".install" or even "-install" should not be part of the naming convention when that is the default expectation and only choice of the program. If a program is only available as a portable program, it shouldn't need a naming convention to show that it's portable when that's the default and only choice, a tag will do. In the situation of multiple "installation" options the package with the installer should default to the program name without any ".install"/"-install" specified in the name and the portable version should get the "-portable" for distinction. I'd like to make a statement on meta packages, but sometimes I don't understand why they exist at all. An example is the AutoHotKey package which is a core team package. For the life of me I can't understand why anyone would want to install the installed AND the portable versions. It doesn't make any sense to me. On top of that they are named ".install" and ".portable" packages instead of "-install"/"-portable" per guidelines. To me, it makes more sense that the package named "autohotkey" should INSTALL AutoHotKey and a package named "autohotkey-portable" should "install" just the portable version. To me, installing the "autohotkey" package should INSTALL AutoHotkey. A meta/virtual for it should have some naming convention designating it as a meta/virtual package so you know you're getting more (in this case) then just the installed program. A name of "autohotkey-virtual" (meta is easier to type, but virtual is easier to understand) would be a good convention. That way if you install the meta/virtual package of "autohotkey-virtual" you know you're getting multiple packages in a group ("autohotkey-group" wouldn't be a bad choice either for the name); while installing the package "autohotkey" would INSTALL AutoHotKey as expected. Another example is my "tivo-desktop" and "tivo-desktop-patch" packages. In most instances people should have the latter installed if they install the first. I haven't made a meta/virtual package for it as I haven't decided on a naming convention that makes sense to me (until maybe now). In this case I should make a "tivo-desktop-group" package that would install the two previously mentioned packages as a group to make a complete and total up-to-date useable program.

Yeah, I know. We're supposed to be discussing tags. If my thoughts above are deemed worthwhile, maybe make an issue of it.

Let's make Chocolatey tags useful and exception based!

ferventcoder commented 7 years ago

Yet I see many many many ".install" and ".portable" packages instead of "-install" and "-portable"

.portable and .install are naming patterns. .extension and .template as well.

ferventcoder commented 7 years ago

The majority of programs have an installer. ".install" or even "-install" should not be part of the naming convention when that is the default expectation and only choice of the program.

It's not. It's considered an anti-pattern if you create a package with .install and you don't have a tri-package (the meta *, *.portable, and *.install)

ferventcoder commented 7 years ago

The meta/virtual is the one you take a dependency on, and eventually based on options, choco will decide which package to install.

ferventcoder commented 7 years ago

According to the documentation (https://github.com/chocolatey/choco/wiki/CreatePackages#naming-your-package)

Right at the bottom of that naming it offers this:

If you are going to offer a package that has both an installer and an archive (zip or executable only) version of the application, create three packages - see Portable vs Installable and Install, Portable, and Meta/Virtual Packages

bcurran3 commented 7 years ago

The meta/virtual is the one you take a dependency on, and eventually based on options, choco will decide which package to install.

Hmmmm, someone asked me why I used AHK portable in my dependencies since they had it installed and was complaining that it was taking up double space. I explained that there was no way for a decision path inside the script and that at the nuspec level it was unknown what they would have.....now I'm seeing there might be a better way. I have to read and understand this better.

If you are going to offer a package that has both an installer and an archive (zip or executable only) version of the application, create three packages - see Portable vs Installable and Install, Portable, and Meta/Virtual Packages

I missed and haven't read those links at the bottom; time for me to review them and then speak up. Also never saw the part before about Chocolatey possibilities on other platforms....

It's not. It's considered an anti-pattern if you create a package with .install and you don't have a tri-package (the meta , .portable, and *.install)

I'm confused if you're agreeing or disagreeing here.

I firmly believe that if you tallied up the packages you'd find the majority use native installers. Everything in DOS going back to CPM has always had defaults. Defaults are a norm. Default are...default! I stand by my comments on defaults and exceptions. Searching, finding, and installing packages should default to the most clear and concise method possible for ease of use. It's counter-intuitive to add ./-install to something that has no other choice. It just makes people think, "What are the other choices? Oh! There are none. Well that was a waste of time."

ferventcoder commented 7 years ago

Searching, finding, and installing packages should default to the most clear and concise method possible for ease of use. It's counter-intuitive to add ./-install to something that has no other choice.

Exactly. We agree with each other here. Unless there are other options, it is an anti-pattern to create a package with ".install" and reduces discoverability.

bcurran3 commented 7 years ago

@pauby Are we any closer to defining a tag and it's purpose?

How about a draft?

AdmiringWorm commented 7 years ago

I would love to see a draft of a documentation of the tags.

Basically for me, just to have something concrete to work with.....

bcurran3 commented 7 years ago

BUMP!

Just checking in.

@pauby can we get a sentence or two? Check in and tell us you're still breathing please. :)

bcurran3 commented 7 years ago

OK, I'll take a stab at defining this...

A tag is a keyword or term used to describe or assign a classification to a package for the purpose of easily finding the package via search. Tags are a requirement in the Chocolatey nuspec file. Most tags are a personal choice, but there are recommended predefined tags as well as some mandatory tags that you need to be aware of.

Below you'll find a list of recommended classification tags:

tagblah1 - description taglbah2 - description

Below you'll find a list of mandatory tags:

mandatorytag1 - description mandatorytag2 - description


reference1 https://en.wikipedia.org/wiki/Tag_(metadata) reference2 https://www.thoughtco.com/what-is-tagging-1701732

ferventcoder commented 7 years ago

Dumping the admin tag by the way folks - anyone have a preference to keep that tag around?

ferventcoder commented 7 years ago

We might build something into the automation to record it on a package push to the community repo (maybe not as a tag, but it would be nice to automatically flag packages in some way as requiring admin rights).

pauby commented 7 years ago

I have been way from this thread for a while. Most of those are due to life getting in the way (I know it sucks). Finish contract. Tiem off. Holidays. Studying. Life. New contract. But I had been getting on top of things this week and I'd carved out this morning to work on Chocolatey bits (packages and coming back to this thread). Anyway. Apologies.

I'm looking at things from top to bottom as there are a lot of posts on here:

@ferventcoder

The development team knows. Search by default is on id, title, description, tags (and maybe some other text field). There are weighting that go into this as well.

I diagree that that is what happens. Yourself, @gep13 and @AdmiringWorm all point to the code but my simple searches show something else. I am still looking for a simple explanation but we've not had one yet.

For me this is one of the biggest issues. We are ploughing on talking about tags, how useful they will be, what we need to use them for and not for and we haven't yet established how the website actually uses them in search. I am more than happy to be proved wrong for no other reason than we can move forward but until we have an agreement on how things actually happen with tags and searching I feel the rest is just fluff.

@ferventcoder

So a vision for tags for me -

  • categorization - this will allow shifting things out into a more dynamic view of packages in the future versus the boring thing that @bcurran3 was mentioning name of the software - although as @dragonwolf83 mentioned, this could be derived from id and title name of the vendor - as @dragonwolf83 mentioned, this could be derived from owners

I agree with this and @dragonwolf83 started this rolling with hsi post which I wholeheartedly agreed with. There is no point in using tags for info that is already part of the package definition (.nuspec).

@ferventcoder

Dumping the admin tag by the way folks - anyone have a preference to keep that tag around?

I'd like to have something around that indicates whether a package needs admin rights or not. But I do agree with earlier suggestions from @bcurran3 that it should be 'notadmin' or something along those lines as that would be the exception rather than the rule as the vast majority of packages require admin right.

@bcurran3

Okay I'll take a stab at defining this

I love the start to this so I thought I'd add my own 2p worth:

=== A tag is a keyword or term used to describe or assign a classification to a package for the purpose of easily finding the package via search. Tags are a requirement in the Chocolatey nuspec file. ~Most tags are a personal choice, but there are recommended predefined tags as well as some mandatory tags that you need to be aware of.~ A list of predefined tags are shown below and split into classifications and administration tags.

Classification Tags. Classifications are open to the package maintainers judgement and are not mandatory (I'd like to see at least one being used mandatory). More than one classification tag can be used (A limit should be introduced I think or we risk getting tag overload).

Administration Tags Administration tags are mandatory if the package meets the criteria for the tag. It is likely that your package will not meet any of the criteria below and therefore have no administration tags.

===

Just my two pence worth.

(1) Updated with @ferventcoder suggestions on portable being used instead of notadmin

ferventcoder commented 7 years ago

One small adjustment:

Portable is a long term concept in Chocolatey and it has a specific definition - does not require admins rights to install or use.

ferventcoder commented 7 years ago

We also discussed the unattended tag at one point for one that would complete successfully without interaction but was not silent.

pauby commented 6 years ago

I have just come back to this thread after having a look at my open issues. I got no notification from Github that it had been updated!

I like the idea of the 'unattended' tag but not the name - I think of all choco packages as unattended by default. My suggestion would be to redefine 'notsilent' as an installation that requires no user interaction but will produce screen output and have a 'notunattended' tag that defines it will need user interaction?

RichiCoder1 commented 6 years ago

Didn't even notice this until now! Gui was had long standing requests for tags and categories. Will read this thread over later :)

teknowledgist commented 6 years ago

I too am just discovering this issue. I like the start by both @bcurran3 and @pauby. If I can throw in my two bits: