TracIni wiki page is incomplete

[jeremy.j.dunn@…]

The TracIni page does not include some configuration options which are mentioned elsewhere.

Specific configurations that are missing:

• tracopt.ticket.deleter referenced for example in #10656, #9823, etc. This is a very useful feature. How do we learn that it exists, and how to use it?
• trac.web.auth.loginmodule The instructions to configure the ​http://trac-hacks.org/wiki/AccountManagerPlugin say to disable the default Trac authentication. Again there is no reference to this configuration on the TracIni page.

Those are just two examples; but I suspect there may be many more undocumented configurations. Is there another wiki page that has a comprehensive list of ALL trac configuration options? Or some other way to discover them, short of reading the source code (I am not a python programmer) ?

[Ryan J Ollos]

I understand your frustration with this aspect of Trac. Presently, the best way to learn about the Trac components is to go to the /admin/general/plugins page and read the component descriptions. This is not ideal though because:

• There are too many components, and components don't map directly to features. The plugins page is cluttered with details of the low-level system architecture.
• Some components don't have descriptions, or lack verbose descriptions.

The issue has been on my mind for a while. Some potential solutions are:

• Provide a higher-level abstraction to the plugin admin page for enabling features. For example, the page could present a checkbox with label Allow tickets to be deleted, and a help string that says Users will TICKET_DELETE permission for the resource will be able to delete tickets and ticket comments.
• Provide better descriptions of components on the plugin admin page.
• Create a TracComponents page with a PluginList macro that displays the available components and their descriptions (or extend the TracIni macro to list components when a keyword argument is passed).

To address your specific points, tracopt.ticket.deleter doesn't have any options so it won't be shown on the TracIni page. In general, the TracIni page is not the right place to look for component descriptions. I don't think we want to go the route of listing all of the components and their descriptions on the TracIni page.

[jeremy.j.dunn@…]

Replying to rjollos:

I understand your frustration with this aspect of Trac.

thank you for your prompt, detailed and thoughtful reply

the best way to learn about the Trac components is to go to the /admin/general/plugins page and read the component descriptions.

AHA! this is what I was missing. It exposes the full feature-set of Trac, from which I can include/exclude features.

In general, the TracIni page is not the right place to look for component descriptions.

Accepted; but then shouldn't there be a high-level page, as a peer with TracIni, TracInterfaceCustomization, etc. (listed in the main sidebar TOC), which is named TracComponents ?

FYI I did spend quite a lot of time trying to answer my own question before opening this ticket; but I was looking only in the documentation, not in my own Trac instance in the Admin section. I just tried again, and I -still- don't see any documentation that corresponds to the various options in /admin/general/plugins, for the core Trac capabilities. Each of the other plugins I have installed has its own documentation; those are not the issue. It's the core feature set I'm asking about.

[Ryan J Ollos]

Replying to jeremy.j.dunn@…:

Accepted; but then shouldn't there be a high-level page, as a peer with TracIni, TracInterfaceCustomization, etc. (listed in the main sidebar TOC), which is named TracComponents ?

Yes, I think that could be the simplest immediate solution, which some of the other ideas for improvement being implemented later. I'll see what the other Trac devs have to say, and then possibly looking into adding it.

We might also benefit from an introduction page that gives a quick overview (TracIntro), along the lines of, this is what trac provides, go here to learn more.

[Jun Omae]

• Create a Trac Components page with a PluginList macro that displays the available components and their descriptions (or extend the TracIni macro to list components when a keyword argument is passed).

I don't think good idea to create such a macro to list installed plugins. It would leak the system information for non-administration accounts. I think the plugin panel in admin is enough.

[Ryan J Ollos]

The way I propose to implement would not leak any information. It would just show the descriptions of all possible components in Trac, both enabled and disabled, and would not indicate any information about the enabled/disabled state, or any plugins. Anyone that knew the Trac version of the installation could easily find the same information.

[Peter Suter]

Better component descriptions sound good to me, and I would have suggested a pointer to admin/general/plugin from TracIni#components-section, but it seems that already exists:

To view the list of active components, go to the Plugins page on About Trac (requires CONFIG_VIEW permissions).

I'm not sure if making that a link would be a good idea.

A PluginList macro could require CONFIG_VIEW. (But for use on a TracComponents page here on t.e.o. that would be unsuitable.)

[jeremy.j.dunn@…]

Replying to psuter:

Better component descriptions sound good to me, and I would have suggested a pointer to admin/general/plugin from TracIni#components-section, but it seems that already exists:

To view the list of active components, go to the Plugins page on About Trac (requires CONFIG_VIEW permissions).

I completely missed that sentence, THREE times. It is not obvious. And, I must say that since the entire page is about "Ini" settings, it never occurred to me to look elsewhere. Honestly the page is so large, I was just scanning down, looking for tabular-format sections with the config options.

The main point here is:

• there are two ways to configure Trac features
  • thru trac.ini
  • thru Admin/General/plugins > Trac core options

Until I posted this ticket and everyone has so kindly replied, I had forgotten completely about the second set of configurations. It would be nice if this was mentioned somewhere OBVIOUS in the main documentation. I still think TracConfiguration would be a helpful top-level topic.

[jeremy.j.dunn@…]

p.s. further to the point I've been suggesting about the need for TracConfiguration, since reading your comments I've been exploring admin > general > plugins > Trac options. Most of the options listed there have -no description-. Searching for them on t.e.o yields nothing. My point is, how is a Trac admin to understand what these features do? Some of them are obvious according to name; but others not so much.

Example: MilestoneCache configuration. Why is it something that can be enabled / disabled? When would I want to disable it?

At a very minimum, it seems like every option listed on that page should have a one-sentence description of what it does.

[Ryan J Ollos]

Replying to psuter:

A PluginList macro could require CONFIG_VIEW. (But for use on a TracComponents page here on t.e.o. that would be unsuitable.)

Use of CONFIG_VIEW could be the way to go, possibly exposing the content on t.e.o by granting CONFIG_VIEW to anonymous for a particular resource using TracFineGrainedPermissions. I'm been considering though, that in a way we already leak information about the configuration through the TracIni macro listing. In many cases a user could figure out the enabled/disabled components by looking at the sections present on the TracIni page. I don't think this is a big problem, but it seems to me that whatever permission restrictions we apply to the use of the TracIni macro may be applicable to a listing of the components and their descriptions. If we are able to list all components regardless of their enabled and disabled status, then essentially no configuration information would be leaked. If we included plugin components in the listing, that would leak the list of installed plugins, but that is not what I had in mind initially.

I confused the situation by saying PluginList, when I should have said ComponentList (or [[TracIni(components)]]) since I had in mind only to show built-in components. If we extended the listing to include plugins, which could be useful, then in many cases we are leaking the same amount of info that is exposed through the current TracIni macro. Arguably more, but I question whether the information is harmful. If we were to apply CONFIG_VIEW to restrict the listing, then we may want to consider requiring CONFIG_VIEW for the TracIni macro as well.

I could see approaching this whole issue from a different direction though. In addition to adding description to all components, some ideas are:

• Improve the layout of the plugin admin page.
• Reduce the number of components shown on the page. Most users would probably prefer that the required components be hidden. Maybe we need more required components. It seems odd to me that trac.db.sqlite_backend.SQLiteConnector is required but trac.db.api.DatabaseManager is not. Another case: can Trac really be used without trac.resource.ResourceSystem? I suppose some projects such as Agilo and Bloodhound might need to replace these classes, but I can't think of any reasons to not make these required.
• We could have a toggle between simple and detailed listing, hiding stuff that typical users would never disable when the simple listing is disabled, such as trac.ticket.api.TicketSystem and trac.resource.ResourceSystem.
• Component dependencies could help reduce the number of components on the page. Many plugins have several components, but they must all be enabled for the plugin to work. It would be nice to have only one component shown in these cases, e.g. show web_ui and hide core, db, api, … We could introduce new attributes, such as required_if and hidden. Of course that only helps if we get plugin authors to add the attributes to their component classes.
• Most of the extra stuff that a standard user would want to enable is in tracopt. Perhaps tracopt could shown as a separate plugin on the admin page.

[Ryan J Ollos]

I'm thinking to proceed as follows:

• Add/improve component descriptions (this ticket).
• Add additional pointers in documentation, directing user to the admin plugins page for descriptions of Trac components.
• Propose displaying tracopt as a separate plugin on the plugin admin page (new ticket).
• Explore other potential improvements later on.

Let me know your thoughts.

[jeremy.j.dunn@…]

re proposed solution in comment:10, all of the points sound good to me. Thank you !

[Peter Suter]

I like almost all of those ideas.

Instead of hiding components I would prefer to just list them separately or maybe just make it more obvious that (and why) they are required.

The dependencies idea might be a bit overkill. Interestingly, the DB backend components are already only required under certain conditions.

[Ryan J Ollos]

Moved ticket assigned to next-stable-1.0.x since maintenance of 1.0.x is coming to a close. Please move the ticket back if it's critical to fix on 1.0.x.

[Ryan J Ollos]

Milestone renamed