{"id":15638678,"url":"https://github.com/rj/relflow","last_synced_at":"2026-02-09T03:31:50.481Z","repository":{"id":26228381,"uuid":"29675071","full_name":"RJ/relflow","owner":"RJ","description":"Version-incrementing, appup-generating, relx-coaxing, workflow-assistant for Erlang projects using rebar3.","archived":false,"fork":false,"pushed_at":"2018-08-13T23:08:48.000Z","size":244,"stargazers_count":92,"open_issues_count":11,"forks_count":17,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-11-02T01:50:47.646Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Erlang","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/RJ.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-01-22T11:14:48.000Z","updated_at":"2023-03-18T19:06:36.000Z","dependencies_parsed_at":"2022-08-01T08:49:00.616Z","dependency_job_id":null,"html_url":"https://github.com/RJ/relflow","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RJ%2Frelflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RJ%2Frelflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RJ%2Frelflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RJ%2Frelflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RJ","download_url":"https://codeload.github.com/RJ/relflow/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223777895,"owners_count":17200950,"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-03T11:22:26.286Z","updated_at":"2026-02-09T03:31:50.371Z","avatar_url":"https://github.com/RJ.png","language":"Erlang","funding_links":[],"categories":[],"sub_categories":[],"readme":"relflow\n=======\n\nRelflow is a release workflow utility for erlang projects that use git and\n[rebar3](https://github.com/rebar/rebar3). It automates the boring bits of generating a reluppable erlang\nrelease, namely:\n\n* writes .appup files for changed applications\n* increments vsn field in .app.src files\n* updates rebar.config with new release version (in relx section)\n\nNB: i've only tested this with standard rebar3 layouts using `apps/` or\n`src/` dirs in the project root.\n\nWorkflow Example\n----------------\n\nYou've shipped your first release to production. Probably built using\n`rebar3 release` (which relies on `relx` internally).\n\nYou tagged your git repo with `first-release` when you shipped the release.\n\nMeanwhile, back in your dev environment, you make a bunch of changes and\nfix some bugs. You test your changes, and commit them to git.\n\nNow it's time to ship an update. Here's what you need to\ndo before building a new release:\n\n* For any apps with added/removed/changed modules, increment the `vsn`\n  field in `.app.src`, and write a suitable `.appup` file to migrate upwards.\n* Increment the release version in the relx section of `rebar.config`\n\nThis is what `relflow` does, so run:\n\n    $ rebar3 relflow -u \"first-release\"\n\nBy default, this will tag and commit the resulting changes to git for\nyou. To see what it did:\n\n    $ git diff HEAD~1  # view diff for last commit\n\nNow you can build the (upgradable) release for the second version.\nNote that the `-u` param here is the erlang release vsn, not a git tag.\n(However, it is sensible to tag the release-commit with the same vsn string).\n\n    $ rebar3 release relup -u \"first-release\"\n\nRationale \u0026 Appup Generation\n----------------------------\n\nExisting release upgrade tools require that you have the previous release\nsitting on disk where you build the upgrade, and will typically use\n[beam_lib:cmp_dirs/2](http://www.erlang.org/doc/man/beam_lib.html#cmp_dirs-2)\nto determine which modules have changed, in order to create an appup.\n\nThis is a pain, because often releases are build on a CI server remotely.\nRelflow depends on git for the list of changed modules. It uses the current\nrebar3 profile to examine BEAMs and check if they are gen_servers, supervisors, etc.\n\nThe implicit assumption here is that modules don't suddenly change from being supervisors to gen_servers or anything weird. If so, the appup would be invalid and require fixing manually.\n\nFor example:\n\n    $ rebar3 as prod relflow -u v12345.6789\n\nThis will use `git diff v12345.6789` for a list of changed modules, and then\ncheck _build/prod/$relname/.. for BEAMs in order to create an appup.\n\nSee [relflow_appup.erl](https://github.com/RJ/relflow/blob/master/src/relflow_appup.erl) for more details.\nIn some cases, you may wish to hand-edit appups, if you have specific dependency ordering requirements.\n\n\nIn-place file rewriting\n-----------------------\n\nrelflow modifies `.app.src` and `rebar.config` files in-place.\nMake sure you have committed all local modifications to git before running relflow.\n\n`.app.src` files are `file:consult`ed, then written out\nusing `io_lib:format` so you lose formatting and comments from them.\n\n`rebar.config` is parsed by line and rewritten to preserve comments\nand whitespace, so you need to format the version like this:\n\n    %% somewhere in rebar.config:\n    {relx, [\n        {release, {myrelname,\n        \"v1.2.3\" %% relflow-release-version-marker\n        }, [\n            app1, cowboy, etc\n        ]},\n        {vm_args, \"./vm.args\"},\n        {sys_config, \"./sys.config\"},\n        {extended_start_script, true},\n        {include_erts, false}\n    ]}.\n\nSpecifically, the rebar.config rewriter looks for a line like this:\n\n        \"v1.2.3\" %% relflow-release-version-marker\n\n..and replaces it like this:\n\n        \"new.version.here\" %% relflow-release-version-marker\n\nSo make sure you format your rebar.config to match.\n\nThis is the only line modified in rebar.config.\n\nUse\n---\n\nAdd the relflow plugin to your `rebar.config`:\n\n\u003cpre\u003e\n{plugins, [\n    {relflow, \".*\", {git, \"https://github.com/RJ/relflow.git\", {branch, \"master\"}}}\n]}.\n\u003c/pre\u003e\n\n\nHelp\n----\n\n    $ rebar3 help relflow\n\n    Relflow\n    =======\n\n    Examples:\n        rebar3 relflow -u v1.2.3        # upgrade from last release, at git tag v1.2.3\n        rebar3 relflow init-versions    # reset all vsns using relflow format\n        rebar3 relflow --version        # print relflow version\n\n\n    Usage: rebar3 relflow [-u \u003cupfrom\u003e] [-x [\u003cnextver\u003e]] [-g [\u003cautogit\u003e]]\n                          [-f [\u003cforce\u003e]]\n\n      -u, --upfrom       Git revision/tag to upgrade from (for appup\n                         generation)\n      -x, --nextversion  The version string to use for the next release\n                         [default: auto]\n      -g, --autogit      Automatically add and commit relflow changes to git\n                         [default: true]\n      -f, --force        Force relflow to run even with uncommitted local\n                         changes [default: false]\n      -v, --version      Print relflow version and exit\n\n\nLicense\n-------\n\nApache2, same as rebar3.\n\nResearch\n--------\n\nOther release / appup generation tools I encountered:\n\n* http://dukesoferl.blogspot.co.uk/2009/05/automatic-appup-file-generation.html (Erlang)\n* rebar2 'generate-appups' https://github.com/rebar/rebar/wiki/Upgrades (Erlang)\n* https://github.com/boldpoker/edeliver (Erlang)\n* https://github.com/davisp/knit (Erlang)\n* https://github.com/bitwalker/exrm (Elixir)\n\nKnit has some nifty [module attributes](https://github.com/davisp/knit#knit-module-attributes) to guide the appup creation (module precedence, dependencies, etc). Warrants further study/copying.\n\nDid I miss any? Let me know!\n\nContact\n-------\n\n* RJ2 on freenode\n* metabrew on twitter\n* rj@metabrew.com\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frj%2Frelflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frj%2Frelflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frj%2Frelflow/lists"}