{"id":17355152,"url":"https://github.com/zephinzer/juniordev-gitversioning","last_synced_at":"2025-03-27T15:22:07.800Z","repository":{"id":79926656,"uuid":"124670369","full_name":"zephinzer/juniordev-gitversioning","owner":"zephinzer","description":null,"archived":false,"fork":false,"pushed_at":"2018-03-11T05:34:22.000Z","size":40,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-02-01T19:14:10.252Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zephinzer.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-03-10T15:50:19.000Z","updated_at":"2018-03-10T15:50:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"9c28a8f2-2be2-435e-84e6-ec7c59ac750e","html_url":"https://github.com/zephinzer/juniordev-gitversioning","commit_stats":{"total_commits":4,"total_committers":1,"mean_commits":4.0,"dds":0.0,"last_synced_commit":"9c526112d729f3c18404331a3b3f6c6712c26dbd"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zephinzer%2Fjuniordev-gitversioning","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zephinzer%2Fjuniordev-gitversioning/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zephinzer%2Fjuniordev-gitversioning/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zephinzer%2Fjuniordev-gitversioning/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zephinzer","download_url":"https://codeload.github.com/zephinzer/juniordev-gitversioning/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245868335,"owners_count":20685609,"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":[],"created_at":"2024-10-15T17:42:29.378Z","updated_at":"2025-03-27T15:22:07.760Z","avatar_url":"https://github.com/zephinzer.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Introduction\n\n# About the Repository\nThe repository can be found at https://github.com/zephinzer/version-tagging-scripts, and it provides for versioning operations that are run in an automated continuous integration/delivery pipeline.\n\n# Why do we Version\nWhen I first became a professional developer, one thing I wasn't used to was versioning.\n\nIn any ways, didn't Git provide the necessary versioning capabilities to rollback to a certain copy of the code?\n\nWell apparently not.\n\n## Code Snapshot\nCode is dynamic, it changes as developers push new features and implement bug fixes. How do we identify an exact copy of the code? This is what versioning is meant for.\n\nGit itself is a system to manage versioning of the code, but it does this in a way that isn't friendly to normal humans - a commit hash. This looks something like: `a3c677046c5b8abec75015773f40743f81a6575c`.\n\n## Human Communication\nSo instead of referring to versions of the code with *\"the one that starts with a, three, c, six, seven...\"*, we created this thing called SEMVER - semantic versioning.\n\nSemantic versioning provides an easier way to communicate versions, and it looks like `1.10.3`, `3.9.15` *et cetera*.\n\nThe first number is called the major version and changes in this number represents new features with non-backward compatibility.\n\nThe second number is called the minor version and changes in this number represents new features with backward compatibility.\n\nThe last number is called the patch version and changes in this number in general represents non-behaviour altering changes such as bug fixes.\n\nWhen a bug is found, users (both non-techies - for products, and developers - for open-source packages) generally report them to developers.\n\nWhen this happens, the version becomes important because it's human friendly.\n\nThink *\"I'm using version 1.0.3 and when I do (x), (y) happens, which is unexpected.\"*\n\n## Automation\n\n### Dependency Management\nLook at the `package.json` of any Node project and you'll find that in the `\"dependencies\"` property, each dependency package has a version associated with it that looks like:\n\n- `~1.0.0`\n- `^2.3.1`\n- `0.3.7`\n\nProper versioning allows us to identify what level of change is permissible for dependencies in our code base.\n\nThe tilda (`~`) indicates that if the remote package has a patch version upgrade, update the local copy too.\n\nThe caret (`^`) indicates that if the remote package has a minor version upgrade, update the local copy too.\n\nThe last but rarely seen way of listing a dependency is:\n\n- `*`\n\nThis indicates to always use the latest version whatever it may be.\n\nAn example of how this might break things can be found in the [`./examples` directory](./examples).\n\n### Continuous Integration/Delivery\nWhen you have a team size of roughly 10 developers and upward, multiple pushes of code happen every day and we often need to find a working copy of the code.\n\nVersioning allows us to identify the copy of the code which works. When all tests pass, we bump the version and tag it to the commit (a version of the code according to Git).\n\n# How Versioning is Implemented\n\n## File Based\nRun the script `./scripts/bump-version-file.sh`. This initialises a `.version` file with `0.0.0`\n\nFile-based versioning is fine for individual developers. But as your team scales, this creates a problem especially when an automatic continuous integration/delivery pipeline is present.\n\nSince the versioning is done by the pipeline, when two or more developers push the code together, this results in a merge conflict since bumping the version requires a commit to be made in the pipeline.\n\n## Git Tag Based\nTo resolve the problem of merge conflcits in the pipeline, we use Git tags to implement versioning.\n\nGit tags exist independently of the files in the repository and are associated with a commit.\n\nPushing of a Git tag is done using `git push --tags` and can be fetched using `git fetch` without causing any file changes.\n\nThe `version-tagging-scripts` repository was made for this purpose.\n\n# Using the Scripts\n\nThe repository allows for the following actions:\n\n**Initialise**\nThis checks for any Git tags with a SEMVER format. If there exists one, nothing is done. If there isn't an existing SEMVER tag, this script will add a new `0.0.0` Git tag.\n\n\u003e Command: `init`\n\n**Iterate**\nThis iterates to the next version and takes an argument of `patch`, `minor` or `major`. The default if no SEMVER selector is indicated is `patch`:\n\n\u003e Command: `iterate [{patch, minor, major}]`\n\n## Manual Inclusion\n\nDownload the zip file into your application directory and unzip it:\n\n```bash\nmkdir -p ./scripts \\\n  \u0026\u0026 curl -o ./scripts/vtscripts.zip -sSL https://github.com/zephinzer/version-tagging-scripts/archive/master.zip \\\n  \u0026\u0026 unzip ./scripts/vtscripts.zip -d ./scripts/vtscripts \\\n  \u0026\u0026 mv ./scripts/vtscripts/*/* ./scripts/vtscripts \\\n  \u0026\u0026 mv ./scripts/vtscripts/*/.* ./scripts/vtscripts \\\n  \u0026\u0026 rm -rf ./scripts/vtscripts/version-tagging-scripts-master;\n```\n\n## Via Gitsubmodules\n\nInside your Git repository, run the following to initialise and use the repository as a Git submodule:\n\n```bash\nmkdir -p ./scripts \\\n  \u0026\u0026 git submodule init \\\n  \u0026\u0026 git submodule add https://github.com/zephinzer/version-tagging-scripts/ ./scripts/vtscripts\n```\n\nFrom a clone of the Git repository, run the following to retrieve the submodule:\n\n```bash\ngit submodule sync \\\n  \u0026\u0026 git submodule update --init --remote\n```\n\nTo completely remove the Git submodule, run:\n\n```bash\ngit rm -f \"scripts/vtscripts\" \\\n  \u0026\u0026 rm -rf \".git/modules/scripts/vtscripts\" \\\n  \u0026\u0026 git config -f .git/config --remove-section \"submodule.scripts/vtscripts\";\n```\n\n## Via Docker\n\nThis tool is also available as a Docker image.\n\nRun the following to use the Docker image to initialise a repository for versioning (sets up a `0.0.0` tag):\n\n```bash\ndocker run -v \"$(pwd):/app\" zephinzer/vtscripts:latest init;\n```\n\nTo bump the patch version:\n\n```bash\ndocker run -v \"$(pwd):/app\" zephinzer/vtscripts:latest iterate patch;\n```\n\nTo bump the minor version:\n\n```bash\ndocker run -v \"$(pwd):/app\" zephinzer/vtscripts:latest iterate minor;\n```\n\nTo bump the major version:\n\n```bash\ndocker run -v \"$(pwd):/app\" zephinzer/vtscripts:latest iterate major;\n```\n\n# Takeaways\n\n- version for human communication\n- versioning your code saves lives\n- favour tags over commits for ease of team scaling","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzephinzer%2Fjuniordev-gitversioning","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzephinzer%2Fjuniordev-gitversioning","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzephinzer%2Fjuniordev-gitversioning/lists"}