Maintenance & docs (was: Ensure svn is up to date when generating public_podlings.json.)

[Shane Curcuru <as...@shanecurcuru.org>]

Sam Ruby wrote on 6/12/17 9:24 PM:
> On Mon, Jun 12, 2017 at 9:06 PM, Sam Ruby <ru...@intertwingly.net> wrote:
...snip...
>> I learned all this the hard way on the original whimsy_vm where
>> directories often got 'wedged' and needed manual intervention for
>> cleanup.  That's why I instituted a hard separation between what can
>> be updated in each process.
> 
> Adding to my answer: this decision (which can be changed if that what
> we collectively want to do) was to prefer slightly stale data over
> data that (at best) might occasionally stop updating, and (at worst)
> can become corrupt.
> 
> The /srv/svn files update every 10 minutes.  For most purposes, that
> is fast enough.

General comments:

- This is a per-tool decision.

- We need to ensure each tool has clear maintenance documentation, so
fixing out of date or bogus data is easy.

- We need to start thinking about how to consistently document these
kinds of things to our users, since the userbase is increasing for many
tools (and overall number of tools total!)

-- Many tools are read-only visualizations of data.  Useful information
is: what does this data mean, how recently was it updated, and where
specifically did it come from (see also test/dataflow.cgi)

-- Read/Write tools should consider explaining how quickly changes take
effect, as well as any auth questions: i.e. are there any tools that
have separate auth from being able to load/see the tool vs. being able
to change any editable data?

-- Some tools should probably explicitly note in the About This Script
that they are access-protected.  This will help remind members to not
share links for some of the member-private data pages, for example.
It's not obvious in many cases to users which specific bits of data
might be member-private vs. committer-private, I think.

Any other "explain to the user what this page is" aspects to cover?


> 
> Programs like the board agenda tool, the secretary mail tool, and now
> the roster take great care to update svn in separate tmp directories.
> 
> - Sam Ruby
> 


-- 

- Shane
  https://www.apache.org/foundation/marks/resources

Re: Maintenance & docs (was: Ensure svn is up to date when generating public_podlings.json.)

[sebb <se...@gmail.com>]

On 13 June 2017 at 13:31, Shane Curcuru <as...@shanecurcuru.org> wrote:
> Sam Ruby wrote on 6/12/17 9:24 PM:
>> On Mon, Jun 12, 2017 at 9:06 PM, Sam Ruby <ru...@intertwingly.net> wrote:
> ...snip...
>>> I learned all this the hard way on the original whimsy_vm where
>>> directories often got 'wedged' and needed manual intervention for
>>> cleanup.  That's why I instituted a hard separation between what can
>>> be updated in each process.
>>
>> Adding to my answer: this decision (which can be changed if that what
>> we collectively want to do) was to prefer slightly stale data over
>> data that (at best) might occasionally stop updating, and (at worst)
>> can become corrupt.
>>
>> The /srv/svn files update every 10 minutes.  For most purposes, that
>> is fast enough.
>
> General comments:
>
> - This is a per-tool decision.
>
> - We need to ensure each tool has clear maintenance documentation, so
> fixing out of date or bogus data is easy.
>
> - We need to start thinking about how to consistently document these
> kinds of things to our users, since the userbase is increasing for many
> tools (and overall number of tools total!)
>
> -- Many tools are read-only visualizations of data.  Useful information
> is: what does this data mean, how recently was it updated, and where
> specifically did it come from (see also test/dataflow.cgi)
>
> -- Read/Write tools should consider explaining how quickly changes take
> effect, as well as any auth questions: i.e. are there any tools that
> have separate auth from being able to load/see the tool vs. being able
> to change any editable data?
>
> -- Some tools should probably explicitly note in the About This Script
> that they are access-protected.  This will help remind members to not
> share links for some of the member-private data pages, for example.

AFAIK the URLs don't contain any secret information, and don't grant
access without further auth.
Whimsy does not use tokens embedded in the URLs.

> It's not obvious in many cases to users which specific bits of data
> might be member-private vs. committer-private, I think.

However screen shots could contain private info.

> Any other "explain to the user what this page is" aspects to cover?
>

From a developer point of view it would be good if the pages could
identify their source files.
There's not always unique text that can be grepped to find the source.

This could be done as comments embedded in the HTML or Javascript.
This could be derived from the __FILE__ constant.
It's trivial in _html blocks, but elsewhere I could not find how to
generate comments.
For example, _{'text'} does not seem to work everywhere.

>>
>> Programs like the board agenda tool, the secretary mail tool, and now
>> the roster take great care to update svn in separate tmp directories.
>>
>> - Sam Ruby
>>
>
>
> --
>
> - Shane
>   https://www.apache.org/foundation/marks/resources