search

matkoniecz / Zazolc

private fork not suitable for general use - it is a customised version of StreetComplete, called Zażółć. Includes some changes that were rejected in StreetComplete, changes unsuitable for general public and features that I test before potential inclusion in StreetComplete
GNU General Public License v3.0
7 stars 0 forks source link

Review line-specific linking, maybe link to specific commit #6

Open matkoniecz opened 2 years ago

matkoniecz commented 2 years ago

extracted from https://github.com/matkoniecz/Zazolc/issues/4 - reported by @mnalis

when linking files and referring to specific line numbers, it would be better to reference specific commit version of that file (even if older/possibly obsolete) then the master. For example, in implement a fully custom tag parsing, still combined with filter syntax links to https://github.com/streetcomplete/StreetComplete/blob/master/app/src/main/java/de/westnordost/streetcomplete/quests/opening_hours/AddOpeningHours.kt#L137-L151 which seems to be wrong line numbers currently.

I hope that recent changes (some triggered by writing this texts, some by linting) will stabilize. I will review links and set reminder to do it again in few months.

mnalis commented 2 years ago

Note you can also link to tag name (i.e. release version), e.g. https://github.com/streetcomplete/StreetComplete/blob/v40.1/app/src/main/java/de/westnordost/streetcomplete/quests/opening_hours/AddOpeningHours.kt#L126-L144

That way it is even shorter then link to master, more readable, and easier to find/change (e.g. "oh, in v50.0 we changed this file, so we need to update all links linking to lower version"), while providing guaranteed stability that docs won't randomly break links or show to wrong parts of files causing more confusion.

But that if you link to master, than you'd basically have to recheck everytime something is updated in master to be sure links didn't broke, which is not only inhuman amount of effort and stressful, or links will go stale and cause confusion to users reading the docs.

Much better to links docs to specific release tag so they won't ever break automatically, and then periodically (at your leisure with no hurry) update them to newer release (making changes to linenumbers as needed).