Re: New maintenance.

[Jan Iversen]

Sent from my iPad

> On 23 Apr 2018, at 00:46, sebb <seb...@gmail.com> wrote:
> 
>> On 22 April 2018 at 15:53, Henk P. Penning <penn...@uu.nl> wrote:
>>> On Sun, 22 Apr 2018, j...@apache.org wrote:
>>> 
>>> Date: Sun, 22 Apr 2018 15:53:52 +0200
>>> From: j...@apache.org
>>> To: general@attic.apache.org
>>> Subject: New maintenance.
>> 
>> 
>>> Based on site-json I propose the following changes:
>>> 
>>> Change docs/scripts/attic.js to project.json (kept as pure json outside
>>> docs).
>> 
>> 
>>  Also, I /really/ would like to have the .json available for 'others',
>>  so inside docs/ please.
> 
> Fine.
> 
> However the source of the data does not have to be in docs so long as
> there is a generated copy in docs.
> 
> There may be info in the source that is not really needed externally
> (so it can be omitted from the docs copy).
> For example 'apply-banner' does not really seem to be relevant to 3rd parties.
> 
> It is easy enough to create a single data file in a suitable format
> for external use as part of the site generation.
> 
>>  Let's call the .json 'attic.json' ;
>>  for 'others' the .json describes what PMC attic has done.
> 
> OK.
> 
>>> Remove xdocs.
>> 
>> 
>>  Ok.
>> 
>>> Allow a build job to monitor for svn changes and if any active a
>>> generation script.
>>> 
>>> The generation script does the following:
>>> - generate a sidebar.inc which is included (physically in all files)
>>> - Generate a page pr. project in projects, based on a 1 template
>>>  “project.md” or similar
>> 
>> 
>>  Eh, no ; if the build scripts creates the attic.js (from a template
>>  and 'attic.json') we are done ; this is much closer to what we have
>>  now.
> 
> What we have now is one XML file per project.
> I am suggesting one Markdown file per project instead.
> 
> This would contain a header with the data values, followed by optional
> body text.
> The data would be processed against a template.
and that is exactly where our opinion split, see my earlier mail. I am vey much 
against the idea of multiple files.
> 
>>> - Generate a flagged directory (if field “flag” is present in the JSON
>>> object”)
>> 
>> 
>>  perhaps we should go with 'retired' (as opposed to 'flagged/')
>>  after all ; this makes it easier to fix the httpd config as
>>  a separate issue ; we'll rm -rf flagged/ later.
> 
> I think the name should relate to the function.
> 'retired' is too general.
> Why not 'add-banner' ?
ok with me.
> 
>>> Ps. I can help to change attic.js, but I am afraid the generate script is
>>> for someone else to write.
>> 
>> 
>>  Can we please go for a simple Makefile ? So we can simply do :
>> 
>>-- svn up
>>-- edit json
>>-- make
>>-- commit
>> 
>> 
>> Sebb,
>> 
>>  I am totally ignorant re: build stuff ; can the build stuff run a make ?
> 
> The buildbot can run any shell command, so it could run make.
> 
> But a simple shell script is likely to be sufficient.
> I don't see any need to use make.
agreed

rgds
jan i
> 
>>  Groeten,
>> 
>>  HPP
>> 
>>    _
>> Henk P. Penning, ICT-beta R Uithof MG-403_/ \_
>> Faculty of Science, Utrecht UniversityT +31 30 253 4106 / \_/ \
>> Leuvenlaan 4, 3584CE Utrecht, NL  F +31 30 253 4553 \_/ \_/
>> http://www.staff.science.uu.nl/~penni101/ M penn...@uu.nl \_/

Re: New maintenance.

[sebb]

On 22 April 2018 at 15:53, Henk P. Penning <penn...@uu.nl> wrote:
> On Sun, 22 Apr 2018, j...@apache.org wrote:
>
>> Date: Sun, 22 Apr 2018 15:53:52 +0200
>> From: j...@apache.org
>> To: general@attic.apache.org
>> Subject: New maintenance.
>
>
>> Based on site-json I propose the following changes:
>>
>> Change docs/scripts/attic.js to project.json (kept as pure json outside
>> docs).
>
>
>   Also, I /really/ would like to have the .json available for 'others',
>   so inside docs/ please.

Fine.

However the source of the data does not have to be in docs so long as
there is a generated copy in docs.

There may be info in the source that is not really needed externally
(so it can be omitted from the docs copy).
For example 'apply-banner' does not really seem to be relevant to 3rd parties.

It is easy enough to create a single data file in a suitable format
for external use as part of the site generation.

>   Let's call the .json 'attic.json' ;
>   for 'others' the .json describes what PMC attic has done.

OK.

>> Remove xdocs.
>
>
>   Ok.
>
>> Allow a build job to monitor for svn changes and if any active a
>> generation script.
>>
>> The generation script does the following:
>> - generate a sidebar.inc which is included (physically in all files)
>> - Generate a page pr. project in projects, based on a 1 template
>>   “project.md” or similar
>
>
>   Eh, no ; if the build scripts creates the attic.js (from a template
>   and 'attic.json') we are done ; this is much closer to what we have
>   now.

What we have now is one XML file per project.
I am suggesting one Markdown file per project instead.

This would contain a header with the data values, followed by optional
body text.
The data would be processed against a template.

>> - Generate a flagged directory (if field “flag” is present in the JSON
>> object”)
>
>
>   perhaps we should go with 'retired' (as opposed to 'flagged/')
>   after all ; this makes it easier to fix the httpd config as
>   a separate issue ; we'll rm -rf flagged/ later.

I think the name should relate to the function.
'retired' is too general.
Why not 'add-banner' ?

>> Ps. I can help to change attic.js, but I am afraid the generate script is
>> for someone else to write.
>
>
>   Can we please go for a simple Makefile ? So we can simply do :
>
> -- svn up
> -- edit json
> -- make
> -- commit
>
>
> Sebb,
>
>   I am totally ignorant re: build stuff ; can the build stuff run a make ?

The buildbot can run any shell command, so it could run make.

But a simple shell script is likely to be sufficient.
I don't see any need to use make.

>   Groeten,
>
>   HPP
>
>    _
> Henk P. Penning, ICT-beta R Uithof MG-403_/ \_
> Faculty of Science, Utrecht UniversityT +31 30 253 4106 / \_/ \
> Leuvenlaan 4, 3584CE Utrecht, NL  F +31 30 253 4553 \_/ \_/
> http://www.staff.science.uu.nl/~penni101/ M penn...@uu.nl \_/

Re: New maintenance.

[sebb]

On 22 April 2018 at 15:48, Jan Iversen <jancasacon...@gmail.com> wrote:
>
>
>> On 22 Apr 2018, at 16:41, sebb <seb...@gmail.com> wrote:
>>
>> On 22 April 2018 at 14:53,  <j...@apache.org <mailto:j...@apache.org>> wrote:
>>> Hi
>>>
>>> Looking at the latest emails, it seems like a compromise between the 2 
>>> solutions are the best solution.
>>>
>>> How about if the combine the proposals to the following (that would make my 
>>> life easier, and hopefully satisfy the majority of problems Sebb see).
>>>
>>>
>>> Based on site-json I propose the following changes:
>>>
>>> Change docs/scripts/attic.js to project.json (kept as pure json outside 
>>> docs).
>>> Remove xdocs.
>>>
>>> Allow a build job to monitor for svn changes and if any active a generation 
>>> script.
>>>
>>> The generation script does the following:
>>> - generate a sidebar.inc which is included (physically in all files)
>>
>> Not sure how you mean the inclusion to work.
>> Do you mean a server-side include? That increases the load on the
>> server, but Infra may agree to it.
>> Or would the project.md template be processed to include the contents?
>
> Sorry for not being clear, yes project.md should automatically include it if 
> possible, otherwise the generator.sh should write it. We want the site to be 
> totally static.
>

OK, so there will need to be a generator script to take the template
and apply each section of the data file to it.

I don't think it makes sense to design a new templating system, so I
think we need to use an existing one.

Do you still object to using Jekyll?

>>
>>> - Generate a page pr. project in projects, based on a 1 template 
>>> “project.md” or similar
>>
>> What would convert project.md into projects/project.html?
> generate.sh or something similar.
>>
>> What about the additional data that is present in many of the XML files?
>> Where would that be stored?
> I suggest to use “description” or add a second field “additional” in JSON, 
> both solutions are OK with me.

Description is not suitable for all the data.

>> It's really awkward to put it in projects.json.
>
> For me, only touching1 file is the highest importance in a new maintenance 
> model, apart from that, you talk about history, this has not happened for a 
> very long time, so it is a onetime effort.

I still don't understand why it is so important to have all the
project data in a single file.

I agree that one should not have to edit two different files to record
the data for a single project, but I don't see what the problem is
with having a single file for each project.
There would still only be a single file to edit, but it would be a
different file for each project.

>>
>>> - Generate a flagged directory (if field “flag” is present in the JSON 
>>> object”)
>>
>> OK.
>>
>>> This solves all URL issues, the concern about JS, all redirection issues as 
>>> far as I can see…and (to me) importantly maintenance is updating 
>>> projects.json and nothing more (related to the site).
>>>
>>> How do you all feel about this compromise ?
>>
>> I think it is closer, but it does not cover the requirement to
>> preserve the existing additional data in the XML files.
>
> Yes, either in “description” (one time effort, even though e.x. taglibs 
> require some editing) or in an additional field (same work).

In either case, adding more than a few words of text to a JSON value
is hard work, especially if there are HTML tags and quotes involved.
Any subsequent maintenance is hard (e.g. to correct spelling etc.)
It is similar to editing compressed CSS.
We should not be creating unmaintainable data files.

> I can guarantee as long as I am the maintener there will not be additional 
> projects with this feature, mainly because that information should already be 
> available on the respective HP.

The information is generally not on the home page because it is not
relevant to an active project.
It is only after the project retires that the additional information
may need to be provided.

> rgds
> Jan I
>>
>>> rgds
>>> Jan I.
>>>
>>> Ps. I can help to change attic.js, but I am afraid the generate script is 
>>> for someone else to write.
>

Re: New maintenance.

[Jan Iversen]

> On 22 Apr 2018, at 16:53, Henk P. Penning <penn...@uu.nl> wrote:
> 
> On Sun, 22 Apr 2018, j...@apache.org wrote:
> 
>> Date: Sun, 22 Apr 2018 15:53:52 +0200
>> From: j...@apache.org
>> To: general@attic.apache.org
>> Subject: New maintenance.
> 
>> Based on site-json I propose the following changes:
>> 
>> Change docs/scripts/attic.js to project.json (kept as pure json outside 
>> docs).
> 
>  Also, I /really/ would like to have the .json available for 'others',
>  so inside docs/ please.
> 
>  Let's call the .json 'attic.json' ;
>  for 'others' the .json describes what PMC attic has done.
OK
> 
>> Remove xdocs.
> 
>  Ok.
> 
>> Allow a build job to monitor for svn changes and if any active a
>> generation script.
>> 
>> The generation script does the following:
>> - generate a sidebar.inc which is included (physically in all files)
>> - Generate a page pr. project in projects, based on a 1 template
>>  “project.md” or similar
> 
>  Eh, no ; if the build scripts creates the attic.js (from a template
>  and 'attic.json') we are done ; this is much closer to what we have
>  now.
> 

I would not use attic.js any longer, it is not needed if we have a build job 
that generates whatever needs to be generated.

>> - Generate a flagged directory (if field “flag” is present in the JSON
>> object”)
> 
>  perhaps we should go with 'retired' (as opposed to 'flagged/')
>  after all ; this makes it easier to fix the httpd config as
>  a separate issue ; we'll rm -rf flagged/ later.
Agree to that.

> 
>> Ps. I can help to change attic.js, but I am afraid the generate script is 
>> for someone else to write.
> 
>  Can we please go for a simple Makefile ? So we can simply do :
> 
>-- svn up
>-- edit json
The part above is online and not part of the build job
>-- make
>— commit
Those 2 should be build job.

> 
> Sebb,
> 
>  I am totally ignorant re: build stuff ; can the build stuff run a make ?
Make or just a script, that is something I would leave to Sebb to decide 
whatever is easier to make and maintain.

To me the “edit json” is the real important part, the rest is just “magic” 
happening :-)

rgds
Jan I
> 
>  Groeten,
> 
>  HPP
> 
>    _
> Henk P. Penning, ICT-beta R Uithof MG-403_/ \_
> Faculty of Science, Utrecht UniversityT +31 30 253 4106 / \_/ \
> Leuvenlaan 4, 3584CE Utrecht, NL  F +31 30 253 4553 \_/ \_/
> http://www.staff.science.uu.nl/~penni101/ M penn...@uu.nl \_/

Re: New maintenance.

[Henk P. Penning]

On Sun, 22 Apr 2018, j...@apache.org wrote:


Date: Sun, 22 Apr 2018 15:53:52 +0200
From: j...@apache.org
To: general@attic.apache.org
Subject: New maintenance.



Based on site-json I propose the following changes:

Change docs/scripts/attic.js to project.json (kept as pure json outside docs).


  Also, I /really/ would like to have the .json available for 'others',
  so inside docs/ please.

  Let's call the .json 'attic.json' ;
  for 'others' the .json describes what PMC attic has done.


Remove xdocs.


  Ok.


Allow a build job to monitor for svn changes and if any active a
generation script.

The generation script does the following:
- generate a sidebar.inc which is included (physically in all files)
- Generate a page pr. project in projects, based on a 1 template
  “project.md” or similar


  Eh, no ; if the build scripts creates the attic.js (from a template
  and 'attic.json') we are done ; this is much closer to what we have
  now.


- Generate a flagged directory (if field “flag” is present in the JSON
object”)


  perhaps we should go with 'retired' (as opposed to 'flagged/')
  after all ; this makes it easier to fix the httpd config as
  a separate issue ; we'll rm -rf flagged/ later.


Ps. I can help to change attic.js, but I am afraid the generate script is for 
someone else to write.


  Can we please go for a simple Makefile ? So we can simply do :

-- svn up
-- edit json
-- make
-- commit

Sebb,

  I am totally ignorant re: build stuff ; can the build stuff run a make ?

  Groeten,

  HPP

   _
Henk P. Penning, ICT-beta R Uithof MG-403_/ \_
Faculty of Science, Utrecht UniversityT +31 30 253 4106 / \_/ \
Leuvenlaan 4, 3584CE Utrecht, NL  F +31 30 253 4553 \_/ \_/
http://www.staff.science.uu.nl/~penni101/ M penn...@uu.nl \_/

Re: New maintenance.

[Jan Iversen]

> On 22 Apr 2018, at 16:41, sebb <seb...@gmail.com> wrote:
> 
> On 22 April 2018 at 14:53,  <j...@apache.org <mailto:j...@apache.org>> wrote:
>> Hi
>> 
>> Looking at the latest emails, it seems like a compromise between the 2 
>> solutions are the best solution.
>> 
>> How about if the combine the proposals to the following (that would make my 
>> life easier, and hopefully satisfy the majority of problems Sebb see).
>> 
>> 
>> Based on site-json I propose the following changes:
>> 
>> Change docs/scripts/attic.js to project.json (kept as pure json outside 
>> docs).
>> Remove xdocs.
>> 
>> Allow a build job to monitor for svn changes and if any active a generation 
>> script.
>> 
>> The generation script does the following:
>> - generate a sidebar.inc which is included (physically in all files)
> 
> Not sure how you mean the inclusion to work.
> Do you mean a server-side include? That increases the load on the
> server, but Infra may agree to it.
> Or would the project.md template be processed to include the contents?

Sorry for not being clear, yes project.md should automatically include it if 
possible, otherwise the generator.sh should write it. We want the site to be 
totally static.


> 
>> - Generate a page pr. project in projects, based on a 1 template 
>> “project.md” or similar
> 
> What would convert project.md into projects/project.html?
generate.sh or something similar.
> 
> What about the additional data that is present in many of the XML files?
> Where would that be stored?
I suggest to use “description” or add a second field “additional” in JSON, both 
solutions are OK with me.

> It's really awkward to put it in projects.json.

For me, only touching1 file is the highest importance in a new maintenance 
model, apart from that, you talk about history, this has not happened for a 
very long time, so it is a onetime effort.

> 
>> - Generate a flagged directory (if field “flag” is present in the JSON 
>> object”)
> 
> OK.
> 
>> This solves all URL issues, the concern about JS, all redirection issues as 
>> far as I can see…and (to me) importantly maintenance is updating 
>> projects.json and nothing more (related to the site).
>> 
>> How do you all feel about this compromise ?
> 
> I think it is closer, but it does not cover the requirement to
> preserve the existing additional data in the XML files.

Yes, either in “description” (one time effort, even though e.x. taglibs require 
some editing) or in an additional field (same work). 

I can guarantee as long as I am the maintener there will not be additional 
projects with this feature, mainly because that information should already be 
available on the respective HP.

rgds
Jan I
> 
>> rgds
>> Jan I.
>> 
>> Ps. I can help to change attic.js, but I am afraid the generate script is 
>> for someone else to write.

Re: New maintenance.

[sebb]

On 22 April 2018 at 14:53,   wrote:
> Hi
>
> Looking at the latest emails, it seems like a compromise between the 2 
> solutions are the best solution.
>
> How about if the combine the proposals to the following (that would make my 
> life easier, and hopefully satisfy the majority of problems Sebb see).
>
>
> Based on site-json I propose the following changes:
>
> Change docs/scripts/attic.js to project.json (kept as pure json outside docs).
> Remove xdocs.
>
> Allow a build job to monitor for svn changes and if any active a generation 
> script.
>
> The generation script does the following:
> - generate a sidebar.inc which is included (physically in all files)

Not sure how you mean the inclusion to work.
Do you mean a server-side include? That increases the load on the
server, but Infra may agree to it.
Or would the project.md template be processed to include the contents?

> - Generate a page pr. project in projects, based on a 1 template “project.md” 
> or similar

What would convert project.md into projects/project.html?

What about the additional data that is present in many of the XML files?
Where would that be stored?
It's really awkward to put it in projects.json.

> - Generate a flagged directory (if field “flag” is present in the JSON 
> object”)

OK.

> This solves all URL issues, the concern about JS, all redirection issues as 
> far as I can see…and (to me) importantly maintenance is updating 
> projects.json and nothing more (related to the site).
>
> How do you all feel about this compromise ?

I think it is closer, but it does not cover the requirement to
preserve the existing additional data in the XML files.

> rgds
> Jan I.
>
> Ps. I can help to change attic.js, but I am afraid the generate script is for 
> someone else to write.

New maintenance.

[jani]

Hi

Looking at the latest emails, it seems like a compromise between the 2 
solutions are the best solution.

How about if the combine the proposals to the following (that would make my 
life easier, and hopefully satisfy the majority of problems Sebb see).


Based on site-json I propose the following changes:

Change docs/scripts/attic.js to project.json (kept as pure json outside docs).
Remove xdocs.

Allow a build job to monitor for svn changes and if any active a generation 
script.

The generation script does the following:
- generate a sidebar.inc which is included (physically in all files)
- Generate a page pr. project in projects, based on a 1 template “project.md” 
or similar
- Generate a flagged directory (if field “flag” is present in the JSON object”)

This solves all URL issues, the concern about JS, all redirection issues as far 
as I can see…and (to me) importantly maintenance is updating projects.json and 
nothing more (related to the site).

How do you all feel about this compromise ?

rgds
Jan I.

Ps. I can help to change attic.js, but I am afraid the generate script is for 
someone else to write.