Add modification data for source files

[finanalyst]

It would be useful to have information about when a source file is modified for

• adding it to the footer of a web page
• adding a <lastmod> option to the sitemap.xml SEO file

This is not trivial.

There are

1. Primary source files, which are pull'ed from the Raku/Doc repository, and the modification date should refer to the last time the source file was modified. This can in principle be done using some git function. An example for the whole site is done when caching the files, and the commit id is found and added to the About page.
2. Structure source files. These include the index.html file. The last modification relates to when the source files are changed, and they are stored on doc-website/Website/structure-sources
3. Composite files. These are generated at build time, so the modification is when they are built.

Resolving this issue would give a user a good understanding how the website is built.

[finanalyst]

@coke @dontlaugh I've nearly completed working on this - an itch that need scratching. Question: As soon as I have eliminated a bug, I propose raising a PR on the docs-dev branch. Any objections?

New system:

• required changes to Pod::From::Cache Raku::Pod::Render and Raku::Collection.
• depends on running git log on the repo for the sources.
• the bug seems to be related to getting git to run on the correct directory

[finanalyst]

@coke @dontlaugh FYI The bug mentioned above actually brings out a fundamental design flaw!

• to get the latest commit id for the 'About' page, which was a community ask, I modified Pod::From::Cache, but in doing so made Pod::From::Cache dependent on git, when it should be neutral about how the sources it gets are retrieved. To get the granular file commits and last edit dates, I used git again.
• the changes in Pod::From::Cache propogate through Raku::Pod::Render.
• Only Raku::Collection gathers the source files. And so Collection, or a plugin for Collection should handle file or repository data.

As far as doc-website is concerned, the commit-id information is added via a Collection plugin called generated, which is then added into a page using a custom block =Generated.

So, I shall be refactoring

• Collection to produce the file-level and repository level information, which can then be accessed by a plugin.
• plugins/generated to access the information, both for the repository and for each file.

[finanalyst]

@coke please look at the current new-raku eg basics-101 to see how I propose to add the commit data. Hover over the 'Edit' button, and then at the bottom of the page, hover over the 'Last edited' footer item. The actual data is wrong because of the above mentioned bug, but this is the User facing interface I proposed.

Any comment?

[coke]

The UI seems fine, but I'm not sure what last edited is going to show (just says not available). Is it the last edit in git? If so, even if that edit hasn't been published?

[dontlaugh]

I haven't had the time to review this, so forgive me if this is already implemented: I think the ideal solution for displaying the website versions is to independently display BOTH git versions, the website code and the content.

When a container is built, it is possible to pass parameters from outside the build. Sometimes this is required for passing in git versions, because the container build context does not always include the .git directories.

I'll take a look later tonight.

[finanalyst]

@coke the last edited value should be a date like 2023-04-13 that is the last vomit date in which the file was changed. Corresponds to 'git log -1 --format="%cs" -- filename'

FWIW I'm thinking of changing this to ... --format="%h %cs" which will put the short commit id followed by the commit date.

[finanalyst]

@dontlaugh I'm refactoring so git data is accumulated when file sources are available, at build time. That should cover all possibilities

On Mon, 15 Apr 2024, 15:52 Coleman McFarland, @.***> wrote:

I haven't had the time to review this, so forgive me if this is already implemented: I think the ideal solution for displaying the website versions is to independently display BOTH git versions, the website code and the content.

When a container is built, it is possible to pass parameters from outside the build. Sometimes this is required for passing in git versions, because the container build context does not always include the .git directories.

I'll take a look later tonight.

— Reply to this email directly, view it on GitHub https://github.com/Raku/doc-website/issues/316#issuecomment-2057053079, or unsubscribe https://github.com/notifications/unsubscribe-auth/AACYZHHLSYT7GLHJXMF6D3LY5PSSBAVCNFSM6AAAAAA6YCV6VKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDANJXGA2TGMBXHE . You are receiving this because you authored the thread.Message ID: @.***>

[finanalyst]

resolved