New Site

[cannikin]

Hello! At the direction of @mojombo I created a new version of the semver.org site. I didn't want to open a PR as it's a repo I started from scratch and wasn't sure if a merge comparison would even work right.

The site is currently deployed to Netlify here: https://semver.netlify.app/

And the repo is here: https://github.com/cannikin/semver.org

Netlify will automatically build and deploy whenever a push to master occurs.

Contributions follow the same pattern as the current site: create a directory in /specs, add _locale.md with the name of your language in the language itself, and then the v2.0.0.md (or whatever version). If you want the big blue hero section to appear then you can translate _hero.html from the English locale.

I use a very simple framework that I built, CameronJS which is just HTML and a couple directives that let you define layouts and partials, pretty simple. Everything is deployed as static HTML with a couple snippets of JS to handle things like the version/language dropdowns and "Copy to Clipboard" links. I have a custom build script that parses the Markdown specs and turns them into the requisite HTML.

[mojombo]

It's true! I thought the SemVer site could use a bit of modernizing in appearance and functionality, and asked @cannikin to help out. Here's what we came up with. It's responsive, so give it a look at various browser widths and on mobile. The version and language are presented in a better way then just listing them all out. Otherwise, things are pretty much the same.

@cannikin one thing we might want to add is little link icons when you hover on sections; the current website offers those, and they are handy to provide.

Let us know what you think!

[klehelley]

I really like it! It stays simple (as it should be) while being a lot more appealing than the current website IMO. I really like the summary in the header.

[Seldaek]

Looking great, definitely a big improvement :)

A couple minor nitpicks:

• <header> would be a bit less lost on wide monitors if it had a max width of some sort. Right now on my screen the language/version pickers are so far out that I had to actively look for them.
• the language in the summary on top is perhaps slightly confusing if you skim it as it contains backwards compatible/backwards incompatible in every item, and missing the distinction between these two is kinda easy. I am not sure how to best improve this, I just thought I'd point it out.

[cannikin]

Updates!

Added anchor tags on headings for @mojombo.

Added max header width so as not to lose the logo/nav at the far ends for @Seldaek. Also tried subtly highlighting the "in" in "incompatible"...how does that feel?

[Seldaek]

Looks good to me! :)

[cannikin]

Awesome! We’ve been deploying everything to Netlify these days. Do we want to do that here? There’s currently a build step during deploy, can GH Pages handle that if it’s not jekyll?

[Seldaek]

I hope someone else can help out with getting this deployed, because I have close to no clue about GH pages.

[cannikin]

I believe GH pages only supports Jekyll sites, which this is not. We can deploy to Netlify, we just need to switch over the DNS. @mojombo do you still have access to that?

…

On Jun 1, 2020, at 12:24 AM, Jordi Boggiano ***@***.***> wrote:  I hope someone else can help out with getting this deployed, because I have close to no clue about GH pages. — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or unsubscribe.

[mojombo]

We need to get the SemVer core team to weigh in. I've contacted them to see if we can move this forward.

[alexandrtovmach]

Github pages can be used as static files hosting, and there are no tricks or jekyll requirements. I'd like to help with deployment process. Firstly we need to negotiate this question with a core team, to host this website under https://github.com/semver/ org

P.S. looks really great, nice job 👍
How about using current SemVer version as main example in a header?

[cannikin]

Github pages can be used as static files hosting, and there are no tricks or jekyll requirements.

Yeah, we'd just have invent a deploy process somewhere that builds the site in master and then commits the updated filesystem to the gh-pages branch and pushes that. Maybe that can be done in a GH Action?

How about using current SemVer version as main example in a header?

Do you mean instead of the big 1.3.4 that's there now? I wanted to have different digits in all positions to give each their own weight and make sure it wasn't implying that like if the minor version is 0 then the patch version must also be 0. Likewise I didn't just want numerical order like 1.2.3 that made it look like that was somehow a requirement.

If anything I should probably change it so that the minor is actually larger than the patch, maybe 1.4.3, to not imply that the numbers always increase from left to right.

Or maybe I've just put too much thought into it. 😃

[jameschensmith]

Great job on this! I'm a bit on the fence for having the version in the hero be either from the SemVer spec version or an example.

1. How would the hero look when the version contains pre-release or build metadata?
2. Would there also be an explanation under pre-release or build metadata like it does with major, minor, patch?

If we are going the example route, I kind of like the idea of flipping between different example versions (one without pre-release or build metadata, with either/or, etc.). With this idea, though, the explanations will keep disappearing and reappearing. 🤔 Just things to think about.

In addition, the select boxes for spec version and languages seem quite long, could we make it scrollable with a max height.

[cannikin]

OKAY finally got back around to these suggestions @jameschensmith, sorry about the delay!

Added the logo as well.

https://semver.netlify.app/

[jameschensmith]

Nice 🙂 Honestly, I think it's a great start, and there can always be iterations on improving the site after this. 👍

[cannikin]

I agree! Any thoughts on how we can go about getting it live? It could live on Netlify and we just need a DNS entry to start serving it at the real domain. This has worked great on the toml.io repo—you get preview deploys of any PRs that are opened (preview deploys for branches are available as well) and any commit to master redeploys the site.

[jameschensmith]

I think that's a great idea! This would model what other specification websites like conventionalcommits.org is doing as well. I don't have much practice with Netlify, but if you need any help I'm open to spending some time to help assist with this. Just let me know 😊

Also, @alexandrtovmach had stated this needs to be discussed by the core team. I'm not sure who they are, but you may need approval from them before you submit a pull request.

[cannikin]

If we went the Netlify route then there's a couple of things we could do:

• Make this codebase master or main in the semver.org repo
• Create a deploy or other new named branch and have Netlify deploy that one

I'm not sure who's on the core team either. Sounds like @alexandrtovmach for sure but not sure who else to include.

[DarkGhostHunter]

Just a minor fix, but the horizontal align of the number should be pixel perfect considering its the main visual key to understand semver.

Chrome 89@Win10

I think using just plain old <table> for that part could help for a quick fix.

[pboling]

@alexandrtovmach @cannikin New site is missing a clear LICENSE. I'd like to use the new logo with a project that uses SemVer, as a link to SemVer.org, and it isn't clear what the license should be for the new logo / new website. The new logo is in the code of the old gh-pages website which I can't seem to find online, but is never referenced or rendered by the live semver.org as far as I can tell, so that's also not a clear indicator.

@maxhaz It looks like you created the logo. Do you have any input on the license for it?

Original Source: semver/semver#171 (comment)
Official Source? https://github.com/semver/semver.org/tree/gh-pages/assets
Converted to SVG: https://simpleicons.org/icons/semver.svg
Author: @maxhaz https://github.com/maxhaz
Pull Request: https://github.com/semver/semver.org/pull/298/files
License: ?

NOTE: An alternate logo was submitted to the logo discussion and made public domain - semver/semver#171 (comment)

[maxhaz]

@pboling Yes, I made the logo that was selected by the community.
I propose to distribute the logo under the permissive Creative Commons Attribution license (CC-BY).

@alexandrtovmach @cannikin Let us know if you have any input on this.

Side note: I noticed that some major projects like Python or Rust have trademarks on their logos, in addition to the CC-BY license (see Python trademark or Rust trademark). If the SemVer organization would like to do the same, it is welcome as well.

[cannikin]

I have no idea what to do about licensing for big, established projects. I just stick MIT on my own stuff and call it a day! Anyone have any opinions either way?

I think projects will trademark their logo so not just anyone can come along and write a book or create a website and slap the logo on it, making it look like it's officially endorsed, or part of, the project. Is this a concern for SemVer I wonder?

[pboling]

For now I'll add a link to the comment by @maxhaz with the suggestion that it be licensed under https://creativecommons.org/licenses/by/4.0/, and (IANAL) since he is the creator, that would be true unless the project it was submitted to had an overriding license guideline.

[jacobdalamb]

The current website looks great, I would just recommend using Astro

[yochem]

It could definitely use a redesign (and the proposed design here looks very good!), but in my opinion it is unnecessary to switch frameworks and build systems for this.

Why use a custom SSG when GH + jekyll handles applying a template, converting from markdown and applying a little css just fine?

[aljgom]

Yes, a redesign would be good, or at least some small formatting improvements to modernize it a bit and improve readability. The Markdown (.md) file on GitHub looks nicer, so maybe just some formatting adjustments could be added to make the website look closer to it. This could make the website look nicer, if diving into a full redesign is too demanding of a task at the moment