Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
m-aciek opened this issue Oct 6, 2017 · 9 comments
Open

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

m-aciek opened this issue Oct 6, 2017 · 9 comments
Labels
build CI and build scripts content Original content related feature i18n Localization

Comments

@m-aciek
Copy link
Contributor

m-aciek commented Oct 6, 2017

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 (b43f3ef, 4fa99c5, aafc4b3).

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

What do you think?

@m-aciek m-aciek changed the title Replace index.mds with symbolic links Replace index.mds with symbolic links to latest document version Oct 6, 2017
@m-aciek
Copy link
Contributor Author

m-aciek commented Aug 2, 2018

@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
Copy link
Contributor

haacked commented Aug 6, 2018

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
Copy link

damianopetrungaro commented Aug 28, 2018

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
Copy link
Contributor Author

m-aciek commented Aug 29, 2018

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

@haacked
Copy link
Contributor

haacked commented Aug 31, 2018

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
Copy link

grv87 commented Dec 4, 2018

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 alexandrtovmach added build CI and build scripts content Original content related feature i18n Localization labels Jun 9, 2020
@alexandrtovmach
Copy link
Member

It's really great idea and I'll investigate to it later. Added to semver/semver#573

@LaoshuBaby
Copy link
Contributor

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
Copy link

yochem commented Jul 17, 2024

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?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
build CI and build scripts content Original content related feature i18n Localization
Projects
None yet
Development

No branches or pull requests

8 participants
@haacked @grv87 @damianopetrungaro @m-aciek @yochem @alexandrtovmach @LaoshuBaby and others