White-labeling and "detracifying"

[Peter Koželj <pe...@digiverse.si>]

Hi,

I would need to add some white-labeling support to Bloodhound. At the same
time I would also use the feature to change or remove some of the Trac
references throughout the application. The credits to the Trac and relation
description between Bloodhound and Trac needs to stay but there are
numerous points where Trac references serve no real purpose but to
potentially confuse new users. So this is I plan of what I intend to do or
is at least worth discussing:

1. Add ability to rename Bloodhound label in ui by changing configuration
file (white-labeling equivalent of i18n file) This same configuration would
be used for replacing Trac references where we would see fit. Personally I
would only leave the reference to Trac in Apps/About Bloodhound

2. Use the configuration for labeling in generated content (email
notifications) configurable

3. Make footer text configurable by the same configuration file

4. Trac version is referenced on all pages, as already said it should be
removed or moved to About page. Code wise references to Trac version happen
on multiple places, sometimes to hardcoded Trac version sometiemes to a
“calculated” one. We need to fix that.

5. Various readme files reference Trac as dependencies. This should be
examined more closely. Given that forked Trac version is bundled with BH it
seems that any dependencies on Trac as external project are not only
unnecessary but actually wrong! There is no white labeling features planned
for this
6. Plugins Kindly ask all plugin authors to take advantage of the new
white-labeling configuration file if it exists, offer white-labling feature
back to Trac.

7. Documentation (wiki) is full of Trac references, pages themselves
contain "Trac" in there name and in addition to that many of the links
contain "Trac" in text as well. And all of this very inconsistent applied.

But there is an even bigger issue with documentation. With BH gaining new
features the Trac documentation will be less and less relevant and may even
become misleading at some point. I would at least remove "Trac" in links
until Trac documentation is replaced by Bloodhound documentation

We could also remove "Trac" from the wiki page names. In fact there is some
code in bloodhound_dashboard/bhdashboard/admin.py
that implies that somebody was already thinking along that lines. Can
someone elaborate?
8. Some of the Trac references appear in the names of the tools and
programming constructs of the Trac itself.
   These do not need to be white-labeled but it would be nice if we could
rename them more neutrally. This include:

  o TRAC_ADMIN premission
  o trac-admin CLI command
  o cleartracd CLI command
  o error handling: TracError is displayed in error report that user sees

---

I intend to do the first 5 or 6 items in the following weeks. For
documentation we would need to decide what do we want to do with it in mid
and long term. Some aspects of 8 can be hard to do and I am not certain yet
if they are worthwile.

Peter

Re: White-labeling and "detracifying"

[Olemis Lang <ol...@gmail.com>]

On 11/11/12, Branko Čibej <br...@wandisco.com> wrote:
> On 11.11.2012 09:52, Peter Koželj wrote:
>> On 8 November 2012 21:53, Olemis Lang <ol...@gmail.com> wrote:
>>
>>> Why not just sections in trac.ini itself rather than a separate file
>>> ? Having many config files/sources will make things a bit difficult
>>> ... afaics . In the end there should always a way to make such
>>> configs fit into INI file structure .
>> Yes, for the first version this will be enough. Later I might still
>> prefer
>> having it in separate file for easier packaging.

Hmmm ... My concern is that if those options will have some impact on
Bloodhound behavior then it'd be nice to have them somewhere in
trac.ini so that plugins and components can read them by using
instances of trac.config.Option or in a way similar to
self.conf.get('section', 'key') . Otherwise we'll have to reinvent
another wheel to do the same thing , which in advance turns out to be
unnecessary .

>> Maybe a file that installer would read and copy the setting over to
>> trac.ini or something but I am not sure if that would be in the scope of
>> Bloodhound the Apache project.
>
> It can be, if you like. It's up to you to decide whether you want to
> bundle an installer script or not.

AFAICR in current installer script [1]_ we should be doing something
like that already in order to perform BH-specific install config steps
e.g. enable AccountManager and other plugins
;)

> It's fairly common practice to have a
> "make install" thing for Unix, for example.
>

There are some of those in Trac too , and we should be able to add our
own make commands as well
;)

.. [1] asf - Revision 1407907: /incubator/bloodhound/trunk/installer
        (https://svn.apache.org/repos/asf/incubator/bloodhound/trunk/installer/bloodhound_setup.py)

-- 
Regards,

Olemis.

Blog ES: http://simelo-es.blogspot.com/
Blog EN: http://simelo-en.blogspot.com/

Featured article:

Re: White-labeling and "detracifying"

[Branko Čibej <br...@wandisco.com>]

On 11.11.2012 09:52, Peter Koželj wrote:
> On 8 November 2012 21:53, Olemis Lang <ol...@gmail.com> wrote:
>
>> Why not just sections in trac.ini itself rather than a separate file
>> ? Having many config files/sources will make things a bit difficult
>> ... afaics . In the end there should always a way to make such
>> configs fit into INI file structure . 
> Yes, for the first version this will be enough. Later I might still prefer
> having it in separate file for easier packaging.
> Maybe a file that installer would read and copy the setting over to
> trac.ini or something but I am not sure if that would be in the scope of
> Bloodhound the Apache project.

It can be, if you like. It's up to you to decide whether you want to
bundle an installer script or not. It's fairly common practice to have a
"make install" thing for Unix, for example.

-- Brane


-- 
Branko Čibej
Director of Subversion | WANdisco | www.wandisco.com

Re: White-labeling and "detracifying"

[Peter Koželj <pe...@digiverse.si>]

On 8 November 2012 21:53, Olemis Lang <ol...@gmail.com> wrote:

> On 11/6/12, Peter Koželj <pe...@digiverse.si> wrote:
> > Hi,
> >
>
> :)
>
> > I would need to add some white-labeling support to Bloodhound. At the
> same
> > time I would also use the feature to change or remove some of the Trac
> > references throughout the application. The credits to the Trac and
> relation
> > description between Bloodhound and Trac needs to stay but there are
> > numerous points where Trac references serve no real purpose but to
> > potentially confuse new users. So this is I plan of what I intend to do
> or
> > is at least worth discussing:
> >
> > 1. Add ability to rename Bloodhound label in ui by changing configuration
> > file (white-labeling equivalent of i18n file) This same configuration
> would
> > be used for replacing Trac references where we would see fit. Personally
> I
> > would only leave the reference to Trac in Apps/About Bloodhound
> >
>
> Why not just sections in trac.ini itself rather than a separate file ?
> Having many config files/sources will make things a bit difficult ...
> afaics . In the end there should always a way to make such configs fit
> into INI file structure .
>

Yes, for the first version this will be enough. Later I might still prefer
having it in separate file for easier packaging.
Maybe a file that installer would read and copy the setting over to
trac.ini or something but I am not sure if that would be in the scope of
Bloodhound the Apache project.


> > 2. Use the configuration for labeling in generated content (email
> > notifications) configurable
> >
>
> What are the options available now to get similar things done ?
>
> > 3. Make footer text configurable by the same configuration file
> >
>
> This is possible already by editing trac.ini
>
> [project]
> footer = Lucy in the Sky with Diamonds
>
> afaicr installer script customizes the footer in default installations
> , but /me not sure .
>

This only work for the right part of the footer. I need something similar
for the left part.


>
> > 4. Trac version is referenced on all pages, as already said it should be
> > removed or moved to About page. Code wise references to Trac version
> happen
> > on multiple places, sometimes to hardcoded Trac version sometiemes to a
> > “calculated” one. We need to fix that.
> >
>
> We need to handle this in a consistent manner . Could you please
> mention examples ?
>

I'll have a look and open a ticket for it. But frankly, I would only
display the Trac version in one place (the About page) and not in the
footer of every page.


>
> > 5. Various readme files reference Trac as dependencies. This should be
> > examined more closely. Given that forked Trac version is bundled with BH
> it
> > seems that any dependencies on Trac as external project are not only
> > unnecessary but actually wrong! There is no white labeling features
> planned
> > for this
>
> I thought we were already stating that we distribute a custom copy of
> Trac , with references to the exact Trac version (relative to svn
> repos) incorporated into vendor branch .
>

Hmm, I can not find it any longer, maybe I was mistaken or was fixed
already.
The bloodhound_dashboard/README does look a bit suspicious though, if
nothing else versions are probably incorrect.


>
> > 6. Plugins Kindly ask all plugin authors to take advantage of the new
> > white-labeling configuration file if it exists, offer white-labling
> feature
> > back to Trac.
> >
>
> IMO that request should be addressed to end users ... but maybe I'm
> missing something .
>

I was referring to the fact that if some plugin uses word "Trac" in it's
UI, it needs to be determined if it should actually use
correct product name ("Bloodhound") when installed in Bloodhound. If that
is the case, plugin should use this new settings instead.


>
> > 7. Documentation (wiki) is full of Trac references,
>
> Yes , Trac-devs did the whole thing
> ;)
>
> > pages themselves
> > contain "Trac" in there name and in addition to that many of the links
> > contain "Trac" in text as well. And all of this very inconsistent
> applied.
> >
>
> We envisioned to migrate default wiki pages onto Guide/ folder (see #85)
>

I'll have a look :)


>
> > But there is an even bigger issue with documentation. With BH gaining new
> > features the Trac documentation will be less and less relevant and may
> even
> > become misleading at some point.
>
> If we will evolve together with Trac then for a reasonable time a
> relevant % of the Trac guide will be valid .
>

Yes, we need to strive to that. But as features are added there will be
cases where existing Trac documentation will be misleading.
And as a user I do not want to guess when to search for something inside
Trac or Bloodhound documentation. But this is already getting way out of
scope on what I am prepare to do as a part of this whitelabeling effort...


>
> > I would at least remove "Trac" in links
> > until Trac documentation is replaced by Bloodhound documentation
> >
> > We could also remove "Trac" from the wiki page names. In fact there is
> some
> > code in bloodhound_dashboard/bhdashboard/admin.py
> > that implies that somebody was already thinking along that lines. Can
> > someone elaborate?
>
> #85 ;)
>
> > 8. Some of the Trac references appear in the names of the tools and
> > programming constructs of the Trac itself.
> >    These do not need to be white-labeled but it would be nice if we could
> > rename them more neutrally. This include:
> >
> >   o TRAC_ADMIN premission
>
> Hard to modify as references to this permission name are scattered all
> over trac and plugins code .
>

Well, search-and-replace would go a long way but I am sure there would be
some complications (plugins?).
Maybe we could suggest it to Trac project, but I doubt they would see
it worthwhile when even I am not sure that it is.


>
> >   o trac-admin CLI command
> >   o cleartracd CLI command
>
> yep
>
> >   o error handling: TracError is displayed in error report that user sees
> >
>
> This one could be «solved» by adding in trac.core something like
>
> {{{
> #!py
>
> class NewNameError(Exception):
>     ... TracError code
>
> TracError = NewNameError
>
> }}}
>
> --
> Regards,
>
> Olemis.
>
> Blog ES: http://simelo-es.blogspot.com/
> Blog EN: http://simelo-en.blogspot.com/
>
> Featured article:
>

Re: White-labeling and "detracifying"

[Olemis Lang <ol...@gmail.com>]

On 11/6/12, Peter Koželj <pe...@digiverse.si> wrote:
> Hi,
>

:)

> I would need to add some white-labeling support to Bloodhound. At the same
> time I would also use the feature to change or remove some of the Trac
> references throughout the application. The credits to the Trac and relation
> description between Bloodhound and Trac needs to stay but there are
> numerous points where Trac references serve no real purpose but to
> potentially confuse new users. So this is I plan of what I intend to do or
> is at least worth discussing:
>
> 1. Add ability to rename Bloodhound label in ui by changing configuration
> file (white-labeling equivalent of i18n file) This same configuration would
> be used for replacing Trac references where we would see fit. Personally I
> would only leave the reference to Trac in Apps/About Bloodhound
>

Why not just sections in trac.ini itself rather than a separate file ?
Having many config files/sources will make things a bit difficult ...
afaics . In the end there should always a way to make such configs fit
into INI file structure .

> 2. Use the configuration for labeling in generated content (email
> notifications) configurable
>

What are the options available now to get similar things done ?

> 3. Make footer text configurable by the same configuration file
>

This is possible already by editing trac.ini

[project]
footer = Lucy in the Sky with Diamonds

afaicr installer script customizes the footer in default installations
, but /me not sure .

> 4. Trac version is referenced on all pages, as already said it should be
> removed or moved to About page. Code wise references to Trac version happen
> on multiple places, sometimes to hardcoded Trac version sometiemes to a
> “calculated” one. We need to fix that.
>

We need to handle this in a consistent manner . Could you please
mention examples ?

> 5. Various readme files reference Trac as dependencies. This should be
> examined more closely. Given that forked Trac version is bundled with BH it
> seems that any dependencies on Trac as external project are not only
> unnecessary but actually wrong! There is no white labeling features planned
> for this

I thought we were already stating that we distribute a custom copy of
Trac , with references to the exact Trac version (relative to svn
repos) incorporated into vendor branch .

> 6. Plugins Kindly ask all plugin authors to take advantage of the new
> white-labeling configuration file if it exists, offer white-labling feature
> back to Trac.
>

IMO that request should be addressed to end users ... but maybe I'm
missing something .

> 7. Documentation (wiki) is full of Trac references,

Yes , Trac-devs did the whole thing
;)

> pages themselves
> contain "Trac" in there name and in addition to that many of the links
> contain "Trac" in text as well. And all of this very inconsistent applied.
>

We envisioned to migrate default wiki pages onto Guide/ folder (see #85)

> But there is an even bigger issue with documentation. With BH gaining new
> features the Trac documentation will be less and less relevant and may even
> become misleading at some point.

If we will evolve together with Trac then for a reasonable time a
relevant % of the Trac guide will be valid .

> I would at least remove "Trac" in links
> until Trac documentation is replaced by Bloodhound documentation
>
> We could also remove "Trac" from the wiki page names. In fact there is some
> code in bloodhound_dashboard/bhdashboard/admin.py
> that implies that somebody was already thinking along that lines. Can
> someone elaborate?

#85 ;)

> 8. Some of the Trac references appear in the names of the tools and
> programming constructs of the Trac itself.
>    These do not need to be white-labeled but it would be nice if we could
> rename them more neutrally. This include:
>
>   o TRAC_ADMIN premission

Hard to modify as references to this permission name are scattered all
over trac and plugins code .

>   o trac-admin CLI command
>   o cleartracd CLI command

yep

>   o error handling: TracError is displayed in error report that user sees
>

This one could be «solved» by adding in trac.core something like

{{{
#!py

class NewNameError(Exception):
    ... TracError code

TracError = NewNameError

}}}

-- 
Regards,

Olemis.

Blog ES: http://simelo-es.blogspot.com/
Blog EN: http://simelo-en.blogspot.com/

Featured article:

Re: White-labeling and "detracifying"

[Joachim Dreimann <jo...@wandisco.com>]

Peter,

thanks for that overview. I suppose it'll be easier to comment on
individual tickets you create for these points than in a single email
thread.

Regarding point 7, we've worked on giving the default wiki pages more
generic names in the past:
https://issues.apache.org/bloodhound/ticket/85

This is currently assigned to be reviewed by Gary.

Cheers,
Joe

On 6 November 2012 08:40, Peter Koželj <pe...@digiverse.si> wrote:

> Hi,
>
> I would need to add some white-labeling support to Bloodhound. At the same
> time I would also use the feature to change or remove some of the Trac
> references throughout the application. The credits to the Trac and relation
> description between Bloodhound and Trac needs to stay but there are
> numerous points where Trac references serve no real purpose but to
> potentially confuse new users. So this is I plan of what I intend to do or
> is at least worth discussing:
>
> 1. Add ability to rename Bloodhound label in ui by changing configuration
> file (white-labeling equivalent of i18n file) This same configuration would
> be used for replacing Trac references where we would see fit. Personally I
> would only leave the reference to Trac in Apps/About Bloodhound
>
> 2. Use the configuration for labeling in generated content (email
> notifications) configurable
>
> 3. Make footer text configurable by the same configuration file
>
> 4. Trac version is referenced on all pages, as already said it should be
> removed or moved to About page. Code wise references to Trac version happen
> on multiple places, sometimes to hardcoded Trac version sometiemes to a
> “calculated” one. We need to fix that.
>
> 5. Various readme files reference Trac as dependencies. This should be
> examined more closely. Given that forked Trac version is bundled with BH it
> seems that any dependencies on Trac as external project are not only
> unnecessary but actually wrong! There is no white labeling features planned
> for this
> 6. Plugins Kindly ask all plugin authors to take advantage of the new
> white-labeling configuration file if it exists, offer white-labling feature
> back to Trac.
>
> 7. Documentation (wiki) is full of Trac references, pages themselves
> contain "Trac" in there name and in addition to that many of the links
> contain "Trac" in text as well. And all of this very inconsistent applied.
>
> But there is an even bigger issue with documentation. With BH gaining new
> features the Trac documentation will be less and less relevant and may even
> become misleading at some point. I would at least remove "Trac" in links
> until Trac documentation is replaced by Bloodhound documentation
>
> We could also remove "Trac" from the wiki page names. In fact there is some
> code in bloodhound_dashboard/bhdashboard/admin.py
> that implies that somebody was already thinking along that lines. Can
> someone elaborate?
> 8. Some of the Trac references appear in the names of the tools and
> programming constructs of the Trac itself.
>    These do not need to be white-labeled but it would be nice if we could
> rename them more neutrally. This include:
>
>   o TRAC_ADMIN premission
>   o trac-admin CLI command
>   o cleartracd CLI command
>   o error handling: TracError is displayed in error report that user sees
>
> ---
>
> I intend to do the first 5 or 6 items in the following weeks. For
> documentation we would need to decide what do we want to do with it in mid
> and long term. Some aspects of 8 can be hard to do and I am not certain yet
> if they are worthwile.
>
> Peter
>



-- 
Joe Dreimann
UX Designer | WANdisco <http://www.wandisco.com/>
*
*
*Transform your software development department. Register for a free SVN
HealthCheck <http://go.wandisco.com/HealthCheck-Sig.html> *