{"id":13685400,"url":"https://github.com/line/headver","last_synced_at":"2025-05-01T04:30:50.681Z","repository":{"id":41844563,"uuid":"381648584","full_name":"line/headver","owner":"line","description":"SemVer compatible version specification that has {head}.{yearweek}.{build} system.","archived":false,"fork":false,"pushed_at":"2024-03-08T00:47:17.000Z","size":99,"stargazers_count":250,"open_issues_count":1,"forks_count":5,"subscribers_count":13,"default_branch":"main","last_synced_at":"2024-08-03T14:09:06.432Z","etag":null,"topics":["convention","semver","specification","version","versioning","versioning-semantics"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/line.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2021-06-30T09:34:54.000Z","updated_at":"2024-07-29T14:31:02.000Z","dependencies_parsed_at":"2024-01-06T02:03:50.597Z","dependency_job_id":"97204208-5c8e-4837-b6bd-654e6e3e334f","html_url":"https://github.com/line/headver","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/line%2Fheadver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/line%2Fheadver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/line%2Fheadver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/line%2Fheadver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/line","download_url":"https://codeload.github.com/line/headver/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224235072,"owners_count":17278079,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["convention","semver","specification","version","versioning","versioning-semantics"],"created_at":"2024-08-02T14:00:50.626Z","updated_at":"2024-11-12T07:30:34.453Z","avatar_url":"https://github.com/line.png","language":null,"funding_links":[],"categories":["Others","others","Tools"],"sub_categories":[],"readme":"# HeadVer Specification\n\n![example](images/example.png)\n\nIt says; the **3rd** public release, at around the **24th week of 2019**, from build **59**.\n\n## Introduction\n\na version specification that has `{head}.{yearweek}.{build}` system.\n\nThe name `HeadVer` stands for **\"only head number is enough to maintain!\"** because it only allows to set the first number manually, and rest numbers are automatic. It simplifies `x.y.z` versioning and gurantees incremental version stamping on top of various versioning scripts introduced in this repository. HeadVer versioning system is battle-tested on the 40+ app/web services.\n\n- `{head}` - manual. Zero-based number.\n- `{yearweek}` - automatic. 2-digit for year and 2-digit for week number.\n- `{build}` - automatic. Incremental number from a build server.\n\n## Code Examples\n\nCurrently, this repository has Bash, Fastlane, and Gradle examples. You can apply it to a build server or a local machine.\n\n- Bash: [examples/bash.md](examples/bash.md)\n- Elixir: [examples/elixir.md](examples/elixir.md)\n- Fastlane: [examples/fastlane.md](examples/fastlane.md)\n- Gradle: [examples/gradle.md](examples/gradle.md)\n- PowerShell: [examples/powershell.md](examples/powershell.md), [examples/headver.ps1](examples/headver.ps1)\n- TypeScript: [examples/typescript.md](examples/typescript.md)\n\n## Motivation\n\nThere are so many questions came out when we use a SemVer style.\n- \"Oops, we accidentally released without updating the version!\" \n- \"Why so many products are still having 1.x.y version? Do we have any chance to increase a major up?\"\n- \"Why `update to 1.0.3` commit should be in commit history? The version number is not a logic but just a package tag.\"\n- \"User got a crash in version 1.4.3 but have no idea how old the version is. Is it outdated for months so?\"\n- \"What was the affected version and how long did we take to get fixed?\"\n- \"In this release, do we update a minor number or patch? We've discussed it all day long.\"\n\nThe HeadVer deeply thought these questions and defined some rules to cover up all of them.\n\n\n## Benefits\n\n- It embraces [SemVer; Semantic Versioning](https://github.com/semver/semver). HeadVer is compatible with `x.y.z` style and easily moves over it.\n- Every number in a version has clear meaning.\n- The middle `{yearweek}` acknowledges an age of a version.\n- It only allows one manual number, the `{head}`, to simplify a numbering consideration and discussion.\n- The build number guarantees each release distinguishable.\n- It is enough to say a `{build}` to point out exact release binary.\n- No same version releases happen even we forgot to do 'version up to x.x.x' commit.\n- `{yearweek}` always has 4-digit long, so we have a minimum validation rule. Every version has fixed 4-digit in the middle.\n\n## Rules\n\n### 1. {head}\n- The first part `{head}` is Zero-based manually modifiable number.\n- For example, if you try to adopt HeadVer to a software that has v2.1.0, it is good to start with head number `3`.\n- In notation, you can say `v3` or `v.3` for the head number `3`.\n\n### 2. {yearweek}\n- The second part `{yearweek}` is a combination of 2-digit for a year and 2-digit week number. ie, 34th week in year 2021 is `2134`.\n- It always has 4-digit.\n- A week number follows **ISO-8601** week date system; https://en.wikipedia.org/wiki/ISO_week_date\n\n### 3. {build}\n- The last part `{build}` is an automatically incremental number, and generally a build server stamps it.\n- We strongly recommend to setup a build server with auto-incremental counter system in front of any software releases.\n- In notation, you can say `b59` or `b.59` for the build `59`.\n\n## Tips\n- If your team is running a weekly sprint, a middle number can be a sprint title as it raises per week. ie, `2104` can be a sprint for 4th week of 2021.\n- If your team is running a bi-weekly sprint, a middle number can also be a sprint title for odd or even numbers.\n- When should we update `{head}` number? We recommend to increase at every end-user receives a new version. ie, for each AppStore releases.\n- `{yearweek}` can be winded back to `0001` when year 2100 comes. When year 2100 comes, update `{head}` or use 4-digit for a year `210001`.\n\n## FAQ\n1. Can we use `-prerelease` for a version? Yes. But practically, we recommend not to use `-` suffix. It is better to update `{head}` instead. HeadVer leads to increase `{head}` actively and frequently.\n1. Can we use `+meta` for a version? Yes, it is perfectly fine.\n1. Why not use `{yyyyMMdd}` but `{yearweek}`? Practically, week number precision is enough.\n\n## Validation\n\nIf you try to implement headver, `{yearweek}` requires special concerns as it should follow ISO8601. Please validate your implementation with below table.\n\n|#| TestCase | Date | {yearweek} | \n|-|----------|--------|------|\n|1|First day of 2012 is Sunday| 2012-01-01 | 1152 |\n|2|First day of 2018 is Monday| 2018-01-01 | 1801 |\n|3|Second day of 2018 is Tuesday| 2018-01-02 | 1801 |\n|4|Seventh day of 2018 is Sunday| 2018-01-07 | 1801 |\n|5|Sixth day of 2018 is Saturday| 2018-01-06 | 1801 |\n|6|First day of 2019 is Tuesday |2019-01-01 | 1901 |\n|7|First day of 2015 is Thursday| 2015-01-01 | 1501 |\n|8|First day of 2010 is Friday| 2010-01-01 | 0953 |\n|9|Last day of 2018 is Monday| 2018-12-31 | 1901 |\n|10|Last day of 2019 is Tuesday| 2019-12-31 | 2001 |\n|11|Last day of 2009 is Thursday| 2009-12-31 | 0953 |\n|12|Last day of 2011 is Saturday| 2011-12-31 | 1152 |\n|13|Last day of 2017 is Sunday | 2017-12-31 | 1752 |\n|14|First day of 2015 for total 53 weeks| 2015-01-01 | 1501 |\n|15|Last day of 2015 for total 53 weeks| 2015-12-31 | 1553 |\n|16|First day of 2016 for total 52 weeks| 2016-01-01 | 1553 |\n|17|Last day of 2016 for total 52 weeks | 2016-12-31 | 1652 |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fline%2Fheadver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fline%2Fheadver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fline%2Fheadver/lists"}