search

bramus / mixed-content-scan

Scan your HTTPS-enabled website for Mixed Content
MIT License
522 stars 51 forks source link

Docs: Fix permalink to Monolog log levels #50

Closed GaryJones closed 7 years ago

bramus commented 7 years ago

Hi @GaryJones,

I see that you link to a specific revision of the doc file, instead of the one in master (https://github.com/Seldaek/monolog/blob/master/doc/01-usage.md#log-levels). Is there a specific reason for this? I'd prefer linking to the file in master, as it'll receive content updates.

Regards, Bramus.

GaryJones commented 7 years ago

I'd prefer linking to the file in master, as it'll receive content updates.

That's exactly what you don't want.

The link I used will always work (short of the Monolog repo being deleted). What is in that specific commit matches to what is implemented inside MCS right now.

If Monolog added in a new level, or changed their numbering, and updated their documentation on master, then, until MCS caught up, there would be a discrepancy. When MCS did catchup, then you would update this link to the Monolog commit that matched.

Likewise, if they moved their documentation (which is why this link got broken in the first place as they moved it into doc/ directory), then this link in the MCS documentation would still correctly link to the Monolog commit that matches what MCS has implemented.

bramus commented 7 years ago

Hi @GaryJones,

I've updated the readme to reflect the changes made in #56 , but kept the link to the master version of the docs.

The logic followed here is that linking to master won't necessitate an update per commit happening to monolog. Only when big changes happen to the monolog repo (such as the docs being split off, or a new version), an update to this readme would be needed.

Thanks for your additions, Bramus.

GaryJones commented 7 years ago

The logic followed here is that linking to master won't necessitate an update per commit happening to monolog.

By linking directly to Monolog master, the MSC link is precisely at risk of breaking on each Monolog commit! Maybe they rename doc/, or change the numbering or title of the doc file - each of those will break the link again.

With a link that includes the commit ID, your link will still work, even if Monolog does go and fiddle with their docs in some way. The commit ID is a permalink. GitHub even has a keyboard shortcut for getting the canonical URL.

This post relates to use of line numbers in a non-canonical URL, but the concept is exactly the same.