docs: fill readme and add comments where needed

README.md

@@ -1,21 +1,42 @@
 # releam
 
-Releam is a gleam package release CLI tool and also a set of utilities for parsing conventional commits
-
 [![Package Version](https://img.shields.io/hexpm/v/releam)](https://hex.pm/packages/releam)
 [![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://hexdocs.pm/releam/)
 
+Releam is an opinionated gleam package release CLI tool and also a set of utilities for parsing conventional commits.
+It is based on the semver and conventional commit specs. Invalid conventional commits will be ignored by this tool.
+
+It is highly inspired by [unjs/changelogen](https://github.com/unjs/changelogen), shoutout to the unjs team for the amazing work in JS land ! You can expect more features comming from this tool in the future.
+
+## Install
 ```sh
-gleam add releam
+gleam add --dev releam
 ```
-```gleam
-import releam
 
-pub fn main() {
-  // TODO: An example of the project in use
-}
+## Usage
+Once you are ready to create a new release from your main git branch, run the following :
+```sh
+gleam run -m releam
+```
+It will :
+- parse the new commits since the last git tag
+- bump your package version
+- generate a changelog based on your conventional commits messages
+- prepend the changelog to your `CHANGELOG.md` (if it's missing it will create it)
+- create a release commit and a new tag
+- if your repository host is supported, it will print a link to your terminal to create a new release (currently only github is supported)
+
+If you have specific requirements, this package exposes all its internal function for you to build your custom release script.
+
+## Configuration
+You can configure automatic git push when running releam by adding this to your `gleam.toml` :
+```toml
+[releam]
+auto_push = true
 ```
+By default, auto push is disabled.
 
+## Documentation
 Further documentation can be found at <https://hexdocs.pm/releam>.
 
 ## Development

gleam.toml

@@ -16,4 +16,4 @@ gleamsver = ">= 1.0.1 and < 2.0.0"
 gleeunit = ">= 1.0.0 and < 2.0.0"
 
 [releam]
-auto_push = false
+auto_push = true

src/releam/changelog.gleam

@@ -28,6 +28,7 @@ pub const changelog_file_path = "./CHANGELOG.md"
 
 const insert_area = "<!-- RELEAM TAG: DON'T DELETE -->\n\n"
 
+/// Generate a Changelog record
 pub fn new(
   package_config: PackageConfig,
   config: ChangelogConfig,
@@ -46,6 +47,7 @@ pub fn new(
   )
 }
 
+/// Renders a changelog to markdown
 pub fn render(changelog: Changelog, with_title with_title: Bool) {
   bool.guard(with_title, render_title(changelog.title), fn() { "" })
   <> render_compare_link(changelog.compare_link)
@@ -59,6 +61,8 @@ pub fn render(changelog: Changelog, with_title with_title: Bool) {
   }
 }
 
+/// Renders a changelog and inject it to the CHANGELOG.md file.
+/// If the file does not exists yet, it will create it.
 pub fn write_to_changelog_file(changelog: Changelog) {
   let assert Ok(_) = case simplifile.is_file(changelog_file_path) {
     Error(_) | Ok(False) -> init_changelog_file()
@@ -82,12 +86,17 @@ pub fn write_to_changelog_file(changelog: Changelog) {
   }
 }
 
+/// Creates a CHANGELOG.md file with a title and the insert area comment.
+/// Insert area comment is used by releam to inject new releases changelogs
+/// after the title and before the previous release changelog
 pub fn init_changelog_file() {
   let assert Ok(_) = simplifile.create_file(changelog_file_path)
   let assert Ok(_) =
     simplifile.append(changelog_file_path, "# Changelog\n\n" <> insert_area)
 }
 
+/// Generates a link to see the list of commits for the new version
+/// if repository host is supported
 fn generate_compare_link(
   package_config: PackageConfig,
   config: ChangelogConfig,
@@ -121,17 +130,20 @@ fn generate_compare_link(
   }
 }
 
+/// Renders changelog's title to markdown
 fn render_title(title: String) {
   "## " <> title <> "\n\n"
 }
 
+/// Renders changelog's compare link to markdown
 fn render_compare_link(link: Result(String, Nil)) {
   case link {
     Ok(l) -> "[compare changes](" <> l <> ")\n\n"
     Error(_) -> ""
   }
 }
 
+/// Renders a commit type header to markdown
 fn render_commit_type_header(commit_type: CommitType) {
   "### "
   <> case commit_type {
@@ -149,6 +161,7 @@ fn render_commit_type_header(commit_type: CommitType) {
   }
 }
 
+/// Renders a commit to markdown as a list item
 pub fn render_commit(commit: Commit) {
   let scope = case commit.conventional_attributes.scope {
     Some(scope) -> "**" <> scope <> "**: "

src/releam/commit.gleam

@@ -28,6 +28,7 @@ pub type Author {
   Author(name: String, email: String)
 }
 
+/// Groups commits by their conventional commit type
 pub fn group_by_commit_type(commits: List(Commit)) {
   let sorter = fn(ct: CommitType) {
     case ct {
@@ -53,6 +54,7 @@ pub fn group_by_commit_type(commits: List(Commit)) {
   })
 }
 
+/// Parses a list of commits from the `git log` output to a list of Commit records
 pub fn parse_list(commits: List(String)) {
   commits
   |> list.map(parse_one)
@@ -61,6 +63,7 @@ pub fn parse_list(commits: List(String)) {
   |> result.unwrap([])
 }
 
+/// Parses a string commit from the `git log` output to a Commit record
 pub fn parse_one(raw: String) {
   let assert Ok(commit_re) =
     regex.compile(

src/releam/conventional_attributes.gleam

@@ -56,6 +56,7 @@ pub type ConventionalOptionalSections {
   )
 }
 
+/// Parses a commit message to a ConventionalAttributes record
 pub fn parse_attributes(message: String) {
   let sections =
     message
@@ -97,6 +98,8 @@ pub fn parse_attributes(message: String) {
   }
 }
 
+/// Parses the first line of commit message to extract
+/// commit type, scope and description
 pub fn parse_definition(def: String) {
   let is_breaking = string.contains(def, "!:")
   let attributes =
@@ -126,6 +129,8 @@ pub fn parse_definition(def: String) {
   }
 }
 
+/// Parses the optional lines of a commit message to extract body and footer.
+/// The list must not include the first line of a commit message
 pub fn parse_optional_sections(sections: List(String)) {
   let footer =
     sections
@@ -161,6 +166,7 @@ pub fn parse_optional_sections(sections: List(String)) {
   }
 }
 
+/// Parses a commit message footer to a dict
 pub fn parse_footer(raw: String) {
   let assert Ok(footer_re) = regex.from_string("^[a-zA-Z0-9-]+:")
   let assert Ok(breaking_change_footer_re) =

src/releam/git.gleam

@@ -6,12 +6,14 @@ import releam/changelog
 import releam/commit_regex
 import shellout
 
+/// Gets the last tag of the repository
 pub fn get_last_tag() {
   exec_git(["describe", "--tags", "--abbrev=0"])
   |> result.unwrap("")
   |> string.replace("\n", "")
 }
 
+/// Gets all commits since the last tag of the repository
 pub fn get_commits_since_last_tag(tag: String) {
   let reference = case tag {
     "" -> "HEAD"
@@ -29,6 +31,9 @@ pub fn get_commits_since_last_tag(tag: String) {
   regex.scan(re, output) |> list.map(fn(m) { m.content })
 }
 
+/// Creates a release commit containing the CHANGELOG.md file and the gleam.toml
+/// with bumped version, creates the new tag and optionaly push to the git
+/// repository
 pub fn commit_release(new_tag: String, push push: Bool) {
   let assert Ok(_) =
     exec_git(["add", changelog.changelog_file_path, "gleam.toml"])

src/releam/package_config.gleam

@@ -21,6 +21,7 @@ pub type PackageConfig {
   )
 }
 
+/// Parses the content of a gleam.toml to return a PackageConfig
 pub fn parse(raw_config: String) {
   let assert Ok(config) = tom.parse(raw_config)
 
@@ -61,6 +62,7 @@ pub fn parse(raw_config: String) {
   PackageConfig(version, repository, auto_push)
 }
 
+/// Replace the package version in a gleam.toml content
 pub fn replace_version(raw_config: String, new_version: gleamsver.SemVer) {
   let assert Ok(version_re) = regex.from_string("version\\s*=\\s*\"(.+)\"")
   regex.replace(

src/releam/release.gleam

@@ -2,7 +2,8 @@ import gleam/uri
 import releam/changelog.{type Changelog}
 import releam/package_config.{type PackageConfig, Github, Repository}
 
-pub fn generate_repository_provider_release_link(
+/// Generates the new release link for supported repository hosts
+pub fn generate_repository_host_release_link(
   package_config: PackageConfig,
   new_changelog: Changelog,
 ) {

src/releam/semver.gleam

@@ -12,6 +12,7 @@ pub type Bump {
   Bump(major: Bool, minor: Bool, patch: Bool)
 }
 
+/// Defines a semver bump type from a list of commits
 pub fn define_bump_type(commits: List(Commit)) {
   case define_bump_type_loop(commits, Bump(False, False, False)) {
     Bump(True, _, _) -> Some(Major)
@@ -32,6 +33,7 @@ fn define_bump_type_loop(commits: List(Commit), bump: Bump) {
   }
 }
 
+/// Defines a semver bump type according to the commit type
 pub fn define_commit_bump_type(current: Commit) {
   case
     current.conventional_attributes.commit_type,