search

semver / semver.org

Semantic Versioning spec and website
https://semver.org
494 stars 281 forks source link

Replace index.mds with symbolic links to latest document version #175

Open m-aciek opened 6 years ago

m-aciek commented 6 years ago

For now there is redundancy in the repository. index.md and spec/v2.0.0.md are intended to be equal for main directory and translations.

It causes confusion and unsyncing of files because of one-file edits in translations (b43f3ef6, 4fa99c5ea, aafc4b32).

Symbolic links would make things simple. Jekyll handles them well on filesystems supporting symbolic links.

What do you think?

m-aciek commented 6 years ago

@Haacked do you have opinion on that? I had started to migrate the files but it looks the are too many files to resolve conflicts for them at once. I would start to make PRs language by language.

I would divide it into smaller pieces:

haacked commented 6 years ago

In theory I love this idea, but the maintenance of it might be challenging. Would it be possible to script this in a batch file/shell script so that we can always fix this up easily?

damianopetrungaro commented 6 years ago

Yeah, it's possible to be done, maybe making a Makefile will be easier to use too.

We are facing the same issue on conventional-commits, probably we'll migrate from jekyll to hugo and we won't need to use symlinks.

I'll probably have some free time this week if it's ok for you I can work on it.

m-aciek commented 6 years ago

The script should work well with git merge-file utility. I tested it locally and all tests were successful so far.

haacked commented 6 years ago

I'm open to the idea. I'm not interested in moving away from Jekyll, so perhaps something I can run locally to fix up the files would work well.

grv87 commented 5 years ago

I think that custom Jekyll plugin put in _plugins dir could duplicate latest specification to index pages either before or after generation. Then the DRY principle would be respected, and complicated git tricks wouldn't be necessary.

Maybe there is an existing plugin, but I couldn't find any.

alexandrtovmach commented 4 years ago

It's really great idea and I'll investigate to it later. Added to https://github.com/semver/semver/issues/573

LaoshuBaby commented 2 years ago

I really like this idea, it will reduce translator's burden on manual sync latest version with index.md, and will not lead to a situation that some translator forget to write index.md but only translate the v2.0.0.md (was fixed in Vietnamese version)

yochem commented 2 months ago

I hadn't noticed this issue yet, but I tried tackling this problem in another way in #448 (at least for the english part). It uses liquid to include spec/v{ current_version }.md. Current version is set in the config file.

I think it would be a good idea to review the complete workflow of getting different version of the spec and building it could be revised. It seems that it could be a lot easier. Also, why not include the translations in the spec repository? Because they are not the "original" spec?