{"id":20563822,"url":"https://github.com/azohra/breadcrumbs","last_synced_at":"2025-04-14T14:53:45.660Z","repository":{"id":57480759,"uuid":"156752643","full_name":"azohra/breadcrumbs","owner":"azohra","description":"An Elixir application for generating release notes","archived":false,"fork":false,"pushed_at":"2018-12-19T21:11:58.000Z","size":28,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-03-15T02:14:38.989Z","etag":null,"topics":["automation","elixir","formatter","jira","release-automation","release-notes"],"latest_commit_sha":null,"homepage":null,"language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/azohra.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-11-08T18:40:59.000Z","updated_at":"2023-12-18T04:30:51.000Z","dependencies_parsed_at":"2022-09-26T22:11:35.060Z","dependency_job_id":null,"html_url":"https://github.com/azohra/breadcrumbs","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azohra%2Fbreadcrumbs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azohra%2Fbreadcrumbs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azohra%2Fbreadcrumbs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/azohra%2Fbreadcrumbs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/azohra","download_url":"https://codeload.github.com/azohra/breadcrumbs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248901310,"owners_count":21180385,"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":["automation","elixir","formatter","jira","release-automation","release-notes"],"created_at":"2024-11-16T04:21:15.049Z","updated_at":"2025-04-14T14:53:45.640Z","avatar_url":"https://github.com/azohra.png","language":"Elixir","readme":"# Breadcrumbs\n\n[![Hex pm](http://img.shields.io/hexpm/v/breadcrumbs.svg?style=flat)](https://hex.pm/packages/breadcrumbs)\n[![GitHub license](https://img.shields.io/github/license/azohra/Breadcrumbs.svg)](https://github.com/azohra/Breadcrumbs/blob/master/LICENSE.md)\n\nAn elixir application that scrapes and renders release notes based on Jira tickets.\n\n## Installation\n\nThe package can be installed by adding `breadcrumbs` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:breadcrumbs, \"~\u003e 0.2.0\"}\n  ]\nend\n```\n\n## Configuration\n\nFirst, you will need to configure the url of your organizations Jira api endpoint:\n\n```elixir\nconfig :breadcrumbs, jira_api_url: \"https://jira.example.com/rest/agile/{version}\"\n```\n\nSecond, you will need to configure the authorization header for your Jira api endpoint:\n\n```Elixir\nconfig :breadcrumbs, jira_api_auth: {\"Authorization\", \"your_key_here\"}\n```\n\nFinally, Breadcrumbs uses a pool of supervised workers to send your api requests concurrently.\nBy default there are 4 workers and each worker can only send one request at a time.\nYou can specify the number of workers like this:\n\n```elixir\nconfig :breadcrumbs, pool_size: 2\n```\n\nAltogether your configuration should look something like this\n\n```elixir\nconfig :breadcrumbs,\n  jira_api_url: \"https://jira.example.com/rest/agile/{version}\",\n  jira_api_auth: {\"Authorization\", \"your_key_here\"},\n  pool_size: 2\n```\n\n## Usage\n\nBreadcrumbs generates release notes using 2 distinct behaiviors: a formatter and a renderer. Renderers define arrangements\nof tickets and formatters define how individual tickets are represented. This seperation is made because the structure of tickets and or\nthe fields contained within them often vary between projects. In order to keep modularity, you can reuse formatters to handle\ndifferent team's tickets, and use different renderers to get different styles of release notes.\n\n---\n\nHere is how to use Breadcrumbs\n\n\n```elixir\n  tickets = [\"SAMPLE-001\", \"SAMPLE-002\", ...]\n\n  # Will use the built-in basic renderer and formatter\n  Breadcrumbs.render(tickets)\n\n  # Or enter the name of a custom module that implements the renderer behaivior\n  Breadcrumbs.render(tickets, CustomRendererModuleName)\n```\n\n### Renderers\n\nRenderers follow the [renderer](lib/breadcrumbs/schema/renderer_spec.ex) behaivior. They recieve a \n[%ScrapeData{}](lib/breadcrumbs/schema/scrape_data.ex) struct which contains a list of [%Ticket{}](lib/breadcrumbs/schema/ticket.ex)\nand a list of [%ErrorTicket{}](lib/breadcrumbs/schema/ticket.ex) that indicate which tickets Breadcrumbs was unable to get.\nThe renderer then goes through tickets and uses a [formatter](lib/breadcrumbs/schema/formatter_spec.ex) to stringify each ticket. \nRenderers then arrange these stringified tickets into a complete release note. A renderer must return a string.\n\n---\n\nOverall, renderers just define the layout of the release note.\n\n--- \n\nHere is Breadcrumbs' built-in renderer. If you design a custom renderer, your implementation of \nrender/1 will define the structure of your release notes, while including or ommiting any data you choose.  \n\n```elixir\n  def render(tickets) do\n    valid =\n      tickets.valid\n      |\u003e Enum.map(fn ticket -\u003e format(ticket) end)\n      |\u003e Enum.reduce(\"Release note:\", fn ticket, message -\u003e appendln(message, ticket) end)\n\n    errors =\n      tickets.errors\n      |\u003e Enum.map(fn ticket -\u003e format(ticket) end)\n      |\u003e Enum.reduce(\"Errors:\", fn ticket, message -\u003e appendln(message, ticket) end)\n\n    appendln(valid, errors)\n  end\n```\n\n### Formatters\n\nFormatters follow the [formatter](lib/breadcrumbs/schema/formatter_spec.ex) behaivior. They recieve a [%Ticket{}](lib/breadcrumbs/schema/ticket.ex) \nor an [%ErrorTicket{}](lib/breadcrumbs/schema/error_ticket.ex) and must return a string. Formatters are responsible for taking required fields \nand formatting them into a string. Some renderers may use multiple formatters if they want to format certain tickets in different \nways.\n\n---\n\nHere is Breadcrumbs' built-in formatter.\n\n```elixir\n  def format(%Ticket{} = ticket) do\n    \"Ticket: #{ticket.key}\"\n  end\n\n  def format(%ErrorTicket{} = error) do\n    \"Error in getting ticket: #{error.key}, Reason: #{error.reason}\"\n  end\n```\n\n## Examples\n\n### Basic Renderer\n\n```\nRelease Notes:\nClosed: SAMPLE-001\nClosed: SAMPLE-002\nErrors:\nError in getting ticket: SAMPLE-003, Reason: not found\n```\n\n## Extending\n\nBreadcrumbs includes a [markdown](lib/breadcrumbs/engine/markdown.ex) module as well as a [utilities](lib/breadcrumbs/engine/utils.ex)\nmodule to aid in custom renderer / formatter implementations.","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazohra%2Fbreadcrumbs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fazohra%2Fbreadcrumbs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fazohra%2Fbreadcrumbs/lists"}