With the release of clog's new website, we should also make the documentation of the project accessible. AFAIK, the documentation is already generated automatically (which is awesome). We now need to deploy it to gh-pages branch, so it can be served by GitHub.

I don't have experience on that but I'll do my best try

@Ryman do you have any experience with Rust on windows? Especially how to automate it? Does it make sense to put windows on a vagrant box and somehow script it to auto generate windows builds?

clog 0.8.1 has 17MB of ./docs in their cargo package source. Since this is 17 MB users shouldn't have to download to depend on the package, consider releasing a new clean version.

This is a reminder that cargo includes all non-ignored files in your working directory when you publish — look at git status before you publish.

(I downloaded all crates.io crates and I started to grep for junk)

When create a new repo, clog -p(or -M, -m), it fails as this:

error: Failed to parse version into valid SemVer. Ensure the version is in the X.Y.Z format.

And, --setversion is not funtional in this case.

Currently the changelog is always generated for the entire history.

This would allow to set a given set of options (--repository, --from-latest-tag)

https://github.com/ajoslin/conventional-changelog/blob/master/lib/writer.js#L82

I don't mind maintaining the repo I'm using to distribute clog via npm, but do you think it would make more sense as part of the clog-tool org? I'd happily transfer it to this org and change it's name to npm-distribution or something (so it doesn't conflict with what's being discussed in #70).

@vyp came up with the great point of allowing users to define custom conventions that can be consumed by clog.

This issue should help us discussing this feature and how we want to implement it. It's clear that we need an AST in order to understand any convention, but therefore we also need a lexer/tokenizer that consumes a context free grammar that is defined by the user.

I'll think about what it could look like from a user perspective when hooking up a custom convention. Any thoughts regarding this implementation are very welcome!

Hi,
I just downloaded clog-v0.7.0_windows-x64.zip binary and when I executed I get the following error:

clog thread '<main>' panicked at 'index 0 and/or 8 in``do not lie on character boundary', C:/bot/slave/stable-dist-rustc-win-64/build/src/libcore\str/mod.rs:1

Do you know how to solve it? I have Win 10 and I don't have installed Rust.

Thanks

Do you mind if I publish the binary to npm? Unless you have some auto-update magic going on that I'm not aware of, it would make getting updates easier (I'd be happy to keep the module updated). I did this with cloc (coincidentally a similar name) and it's been handy to be able to simply install it globally using the same package manager that I'm used to. I think it would help adoption as well.

Let me know what you think.

This is really just for better UX:

Whenever I create or update a changelog with clog the output I get is always:

$ changelog updated (took xx ms)

I think it'd be nicer if the tools states that it created a changelog, if that's the case and only updates if that's the case.

I encountered a behaviour which I consider a bug, but I might be wrong. This is my commit history:

* 2970d06 (HEAD, tag: 1.1, master) fix(lexer): tokenize more strict
* 083c40b (tag: 1.0) fix(compiler): adds missing constructor parameter
* ecc200d fix(compiler): adds missing constructor
* c5c2471 feat(compiler): implements lexer
* 6603503 chore: initial commit

As we can see, there's only one commit for lexer. Generating a changelog, gives me this output:

Component lexer doesn't have a list. IMO even if there's only a single message for a component, a list should be generated.

Currently, clog creates a markdown file by default. As discussed in #57, I think it'd make sense if writers could be swapped out.

This raises my next question: Unix commands usually write to stdout by default. If we implement a writer abstraction, so we can plug more into clog, we shouldn't prefer one over the other. Which brings me to the point, that it might be better if clog writes to stdout by default.

Of course, this adds the complexity that you always have to provide a writer option in case you don't want to write to stdout, but this is how most/all UNIX commands work.

Thoughts on this?

I wanted to create a CHANGELOG for a repo, that already had some history and releases - thankfully the commits were all in the same style. Let's assume the repo already had two releases: 0.1.0 and 0.2.0.

So I expcted, that after the execution of the following commands, I would have a CHANGELOG file with the correct history.

clog --setversion 0.1.0 --from 123 --to 456 -C CHANGELOG.md
clog --setversion 0.2.0 --from 456 --to 789 -C CHANGELOG.md

As the docu stated --from and --to assume a commit hash. But after frustation of why clog didn't found the commit hash, I looked into the code and found, that --from works only with a version tag - which it then did. But for --to neither a version tag nor a commit hash worked and I couldn't find any actual implementation for that CLI option, either.

My versions, installed about a day (24 hours) ago:

$ rustc --version
rustc 0.13.0-nightly (99d6956c3 2014-12-18 20:32:07 +0000)

$ cargo --version
cargo 0.0.1-pre-nightly (5af754d 2014-12-18 01:50:48 +0000)

If it matters, I'm on arch linux, using the rust-nightly-bin and cargo-nightly-bin AUR packages.

cargo build in this repository gives (what looks like) syntax errors when attempting to build docopt. Their latest commits and release (0.6.16) fixes this.

So cargo update -p docopt, and then cargo build --verbose results in the following error:

       Fresh docopt v0.6.16 (https://github.com/docopt/docopt.rs#3f39bcc7)
       Fresh docopt_macros v0.6.16 (https://github.com/docopt/docopt.rs#3f39bcc7)
   Compiling clog v0.2.0 (file:///home/rws/code/gen/clog2)
     Running `rustc /home/rws/code/gen/clog2/src/main.rs --crate-name clog --crate-type bin -g --out-dir /home/rws/code/gen/clog2/target --dep-info /home/rws/code/gen/clog2/target/.fingerprint/clog-76bd6c1d8f39f9ac/dep-bin-clog -L /home/rws/code/gen/clog2/target -L /home/rws/code/gen/clog2/target/deps --extern docopt_macros=/home/rws/code/gen/clog2/target/deps/libdocopt_macros-c59a259f9c0bfb33.so --extern docopt=/home/rws/code/gen/clog2/target/deps/libdocopt-29a30eb0650840d7.rlib`
/home/rws/code/gen/clog2/src/main.rs:41:34: 41:35 error: macros that expand to items must either be surrounded with braces or followed by a semicolon
/home/rws/code/gen/clog2/src/main.rs:41   flag_setversion: Option<String>)
                                                                         ^
error: aborting due to previous error
Could not compile `clog`.

Caused by:
  Process didn't exit successfully: `rustc /home/rws/code/gen/clog2/src/main.rs --crate-name clog --crate-type bin -g --out-dir /home/rws/code/gen/clog2/target --dep-info /home/rws/code/gen/clog2/target/.fingerprint/clog-76bd6c1d8f39f9ac/dep-bin-clog -L /home/rws/code/gen/clog2/target -L /home/rws/code/gen/clog2/target/deps --extern docopt_macros=/home/rws/code/gen/clog2/target/deps/libdocopt_macros-c59a259f9c0bfb33.so --extern docopt=/home/rws/code/gen/clog2/target/deps/libdocopt-29a30eb0650840d7.rlib` (status=101)

So add in a semicolon at the end of line 41 in src/main.rs, and then cargo build --verbose results in the following error:

       Fresh docopt v0.6.16 (https://github.com/docopt/docopt.rs#3f39bcc7)
       Fresh docopt_macros v0.6.16 (https://github.com/docopt/docopt.rs#3f39bcc7)
   Compiling clog v0.2.0 (file:///home/rws/code/gen/clog2)
     Running `rustc /home/rws/code/gen/clog2/src/main.rs --crate-name clog --crate-type bin -g --out-dir /home/rws/code/gen/clog2/target --dep-info /home/rws/code/gen/clog2/target/.fingerprint/clog-76bd6c1d8f39f9ac/dep-bin-clog -L /home/rws/code/gen/clog2/target -L /home/rws/code/gen/clog2/target/deps --extern docopt_macros=/home/rws/code/gen/clog2/target/deps/libdocopt_macros-c59a259f9c0bfb33.so --extern docopt=/home/rws/code/gen/clog2/target/deps/libdocopt-29a30eb0650840d7.rlib`
/home/rws/code/gen/clog2/src/log_writer.rs:1:5: 1:39 error: unresolved import `std::collections::hashmap::HashMap`. Could not find `hashmap` in `std::collections`
/home/rws/code/gen/clog2/src/log_writer.rs:1 use std::collections::hashmap::HashMap;
                                                 ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/home/rws/code/gen/clog2/src/common.rs:2:5: 2:39 error: unresolved import `std::collections::hashmap::HashMap`. Could not find `hashmap` in `std::collections`
/home/rws/code/gen/clog2/src/common.rs:2 use std::collections::hashmap::HashMap;
                                             ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/home/rws/code/gen/clog2/src/section_builder.rs:1:5: 1:39 error: unresolved import `std::collections::hashmap::HashMap`. Could not find `hashmap` in `std::collections`
/home/rws/code/gen/clog2/src/section_builder.rs:1 use std::collections::hashmap::HashMap;
                                                      ^~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
/home/rws/code/gen/clog2/src/section_builder.rs:2:5: 2:30 error: unresolved import `std::collections::hashmap`. There is no `hashmap` in `std::collections`
/home/rws/code/gen/clog2/src/section_builder.rs:2 use std::collections::hashmap;
                                                      ^~~~~~~~~~~~~~~~~~~~~~~~~
/home/rws/code/gen/clog2/src/section_builder.rs:3:37: 3:44 error: unresolved import `common::Feature`. There is no `Feature` in `common`
/home/rws/code/gen/clog2/src/section_builder.rs:3 use common::{ LogEntry, SectionMap, Feature, Fix };
                                                                                      ^~~~~~~
/home/rws/code/gen/clog2/src/section_builder.rs:3:46: 3:49 error: unresolved import `common::Fix`. There is no `Fix` in `common`
/home/rws/code/gen/clog2/src/section_builder.rs:3 use common::{ LogEntry, SectionMap, Feature, Fix };
                                                                                               ^~~
/home/rws/code/gen/clog2/src/git.rs:3:26: 3:33 error: unresolved import `common::Feature`. There is no `Feature` in `common`
/home/rws/code/gen/clog2/src/git.rs:3 use common:: { LogEntry, Feature, Fix, Unknown };
                                                               ^~~~~~~
/home/rws/code/gen/clog2/src/git.rs:3:35: 3:38 error: unresolved import `common::Fix`. There is no `Fix` in `common`
/home/rws/code/gen/clog2/src/git.rs:3 use common:: { LogEntry, Feature, Fix, Unknown };
                                                                        ^~~
/home/rws/code/gen/clog2/src/git.rs:3:40: 3:47 error: unresolved import `common::Unknown`. There is no `Unknown` in `common`
/home/rws/code/gen/clog2/src/git.rs:3 use common:: { LogEntry, Feature, Fix, Unknown };
                                                                             ^~~~~~~
/home/rws/code/gen/clog2/src/main.rs:17:5: 17:23 error: unresolved import `docopt::FlagParser`. There is no `FlagParser` in `docopt`
/home/rws/code/gen/clog2/src/main.rs:17 use docopt::FlagParser;
                                            ^~~~~~~~~~~~~~~~~~
error: aborting due to 10 previous errors
Could not compile `clog`.

Caused by:
  Process didn't exit successfully: `rustc /home/rws/code/gen/clog2/src/main.rs --crate-name clog --crate-type bin -g --out-dir /home/rws/code/gen/clog2/target --dep-info /home/rws/code/gen/clog2/target/.fingerprint/clog-76bd6c1d8f39f9ac/dep-bin-clog -L /home/rws/code/gen/clog2/target -L /home/rws/code/gen/clog2/target/deps --extern docopt_macros=/home/rws/code/gen/clog2/target/deps/libdocopt_macros-c59a259f9c0bfb33.so --extern docopt=/home/rws/code/gen/clog2/target/deps/libdocopt-29a30eb0650840d7.rlib` (status=101)

This is where I decided to stop and open this issue, because I have little to no knowledge of rust yet (just started).

Hey everyone,

I'm currently working on a nice little website for the project so we can promote it a little bit better and also because, awesome projects deserve awesome websites. It's really just about making a nice landing page with all the needed information to get started and some links to the GitHub repo and the docs (which we will publish on gh-pages through this repo).

Here's a screenshot of the work-in-progress:

Would love to hear your thoughts! Feedback is highly welcome. Also, it'd be nice if we could brainstorm a little bit about the content of the site. Maybe you have some cool ideas.

In addition to that, @Nevraeka is so kind to help us out and works on a very nice logo too, based on this scribble:

It'd be nice to have a 1.0 milestone and mark particular issues against that milestone to be able to track progress. I'd set this up, but I'm not sure which issues @cburgdorf and @PascalPrecht want to be 1.0 priorities/blockers.

I'd suggest: #52 #53 #55 #56 #58 #60 and #62

It's currently a bit unfortunate that clog's core functionality isn't available as a lib. If I want to write another app that wants to use clog I would have to find a way to bundle the binary with my app and call it as another process. But that doesn't seem to be easily supported by cargo yet.

//cc @kbknapp

I wonder if we should use a flag like --file-mode=append / --file-mode=new for that. But then on the other hand, it's trivial to rm changelog if one wants to have a new file. It seems to be more aligned with the UNIX way of thinking to just always append and use rm if one wants the opposite.

Currently we ship with only Bug Fixes and Features the angular conventions we link to uses quite a few more sections as well. It'd be nice to ship with a few more of the default sections, perhaps not all of them, but at least a few that are nice to display in a changelog (such as performance, test, docs, etc.)

The conventional changelog description lists:

Breaking Changes are detected as such if the footer contains a line starting with BREAKING CHANGE: (with optional newlines) The rest of the commit message is then used for this.

I couldn't find anything in the repo referencing 'breaking', and the tool hasn't been picking them up, so I'm assuming this is unimplemented. Is this a missing feature, or have I overlooked something?

Hello everybody @kbknapp

I am not sure what i am doing wrong. I use Arch Linux and i have installed clog-git from the AUR, I have proved too with git-bin but the result is the same.

After execute

clog -r https://github.com/clog-tool/clog-cli --outfile only_new.md

I always obtain a file with only two lines
only_new.md.zip

Could someone help me to find out where is my mistake?

Thanks in advance

In clap we've been using Rust-highfive and Homu to assist with contributions. Rust-highfive (@yo-bot) automatically assigns a reviewer to PRs from a pool of contributors and allows things like reassigning to another reviewer with r? @user which is nice for things like replying from e-mail.

Homu (@homu) on the other hand tests and auto-merges PRs once a reviewer has reviewed and accepted a PR by using @homu r+.

Thoughts on adding these for the clog repos? Homu is a hosted service (free), and Rust-highfive is a free service hosted on a VPS I've got.

@cburgdorf Just did some dep updates but 0.9.2 hasn't been published yet.

ft(x) should expand to feat(x)
fx(x) should expand to fix(x)
rf(x) should expand to refactor(x)
ch(x) should expand to chore(x)

clog's readme is quite comprehensive, which is great. However, it still misses the most simple example on how to use it. We already display the output of clog --help but it'd be great to see how I can generate a changelog from a single command.

As far as I can see, the code base is already structured and spit into library and cli code. Now that we moved the code to this organisation, we could also consider having a dedicated cli and lib repo.

Thoughts?

I am not sure if Clog or Clog-CLI currently aggrees on an explicit standard for the change logs it generates, but I think that would have a tremendious impact on the Rust crate ecosystem.

Many points are pointed out in this post. But to summarize a standard on how a change log should look (as well as the file name e.g. CHANGELOG.md), would lead to a parseable crate ecosystem and would help spreading best practices faster.

A lot of work on standarizing was already done by http://keepachangelog.com/ and https://github.com/tech-angels/vandamme/ . Basing Clog on such a standard would bring the Rust crate system forward. Happy to discuss thoughts on this :)

An agreed standard would help to resolve some minor issues I would propose such as:

• Referencing Issues in the changelog (e.g. CLOSED)
• Referencing the authors
• Adding semantic versioning support
• And discussing the overall structure/outline. KeepAChangelog, proposeses e.g. also deprecation and security notes

Currently only two sections become viewable in the changelog, Features and Fixes. I'd propose allowing users to define additional sections, and the aliases of those sections in their .clog.toml

This issue would allow adding sections (and aliases) only, i.e. not taking away of the standard sections and aliases.

I'm thinking something like

[clog]
# ...

[sections]
MyCustom = ["mc", "mycust"]

With the new #64 PR I realized that clog cannot currently read an old changelog and save to a new location. If it reads from an old changelog, it always writes back out to that location. It may be useful to allow reading from an old changelog and outputting to a new one, or arbitrary location.

Imagine wanting to run clog and suck up all the old data, but output to stdout? Currently you can't. It either reads everything from the old one, and writes back out to it, or doesn't read the old one and prints to stdout.

What do you think?

They differentiate between regular and patch versions:

https://github.com/ajoslin/conventional-changelog/blob/37f5561553c30d8f0f2c949502ea278da64949cd/lib/writer.js#L94-L96

Love the work that is happening here.

However, whereas the readme describes how I can use clog as a library, there's no information on how I can install and use the binaries. I know, it might be obvious to a lot of people, but to make it even easier for everyone, It'd be nice if there was a n instruction that tells you where to download the binary, where to put it on your system and finally, that you might have to configure your $PATH and how.

@vyp

To alleviate some of the discussion from #20 I've started this issue.

I've uploaded a rust-beta-bin package to the AUR which you can use in your makedepends array since we're targeting stable Rust (even though clog should also build just fine with nightly). This provides cargo and rust so you won't need to specify those as a make-dep any more.

It would be nice if there was both a command line option, and a config file parameter to specify the name of the changelog file. In particular it seems it's very common to call the file "CHANGELOG.md", where as the filename in clog is hard coded currently to "changelog.md".

Clog repositories are piling up in the thoughtram organisation, which is not a deal breaker, but it might be nicer to have an organisation for that project. We currently have repos for the cli tool (maybe even the library get's it's own repo in the future? @kbknapp), the website, logo media and so on and so forth. We might even end up with corresponding server repositories.

What do you think?

If no version is supplied and no repository link (e.g. cargo run) then the output is:

<a name=""</a>
##  (2014-09-26)

compared to something with a version & repository link:

## 0.2.0 (2014-09-23)

So, other than the minor bug in the anchor tag (unclosed tag and I think the logic is reversed?).

I think the version should be a required value, or print the date without brackets, or print a branch+sha1 as a version number. Either way something's fishy about that a tag and I'm not sure what's intended.

This should probably go either in the README.md or the documentation somewhere.

I would also recommend putting a manual --from <hash> in the Try it section. Because right now, the .clog.toml for this project uses from-latest-tag = true which won't show a whole lot to the user trying it if not much has changed.

Clog creates and writes markdown files by default. I think there are also use cases, where don't want markdown as output, but rather JSON. It'd be cool if we could plug in any writer, as long as it implements a certain interface. The writer could then be configurable through .clog.toml and cli options.

LogWriter would then just be another writer that can be plugged into clog.

@kbknapp @cburgdorf wdyt?

Is there any way clog-cli can parse a github PR commit message ? In our workflow, we do use feature/branch and are using PR only. When we merge the PR, we set the conventional commit message into the long commit message of the PR but clog fails to parse this part of the commit.

This issue was automatically generated. Feel free to close without ceremony if
you do not agree with re-licensing or if it is not possible for other reasons.
Respond to @cmr with any questions or concerns, or pop over to
#rust-offtopic on IRC to discuss.

You're receiving this because someone (perhaps the project maintainer)
published a crates.io package with the license as "MIT" xor "Apache-2.0" and
the repository field pointing here.

TL;DR the Rust ecosystem is largely Apache-2.0. Being available under that
license is good for interoperation. The MIT license as an add-on can be nice
for GPLv2 projects to use your code.

Why?

The MIT license requires reproducing countless copies of the same copyright
header with different names in the copyright field, for every MIT library in
use. The Apache license does not have this drawback. However, this is not the
primary motivation for me creating these issues. The Apache license also has
protections from patent trolls and an explicit contribution licensing clause.
However, the Apache license is incompatible with GPLv2. This is why Rust is
dual-licensed as MIT/Apache (the "primary" license being Apache, MIT only for
GPLv2 compat), and doing so would be wise for this project. This also makes
this crate suitable for inclusion and unrestricted sharing in the Rust
standard distribution and other projects using dual MIT/Apache, such as my
personal ulterior motive, the Robigalia project.

Some ask, "Does this really apply to binary redistributions? Does MIT really
require reproducing the whole thing?" I'm not a lawyer, and I can't give legal
advice, but some Google Android apps include open source attributions using
this interpretation. Others also agree with
it.
But, again, the copyright notice redistribution is not the primary motivation
for the dual-licensing. It's stronger protections to licensees and better
interoperation with the wider Rust ecosystem.

How?

To do this, get explicit approval from each contributor of copyrightable work
(as not all contributions qualify for copyright, due to not being a "creative
work", e.g. a typo fix) and then add the following to your README:

## License

Licensed under either of

 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
 * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

### Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
additional terms or conditions.

and in your license headers, if you have them, use the following boilerplate
(based on that used in Rust):

// Copyright 2016 clog-cli Developers
//
// Licensed under the Apache License, Version 2.0, <LICENSE-APACHE or
// http://apache.org/licenses/LICENSE-2.0> or the MIT license <LICENSE-MIT or
// http://opensource.org/licenses/MIT>, at your option. This file may not be
// copied, modified, or distributed except according to those terms.

It's commonly asked whether license headers are required. I'm not comfortable
making an official recommendation either way, but the Apache license
recommends it in their appendix on how to use the license.

Be sure to add the relevant LICENSE-{MIT,APACHE} files. You can copy these
from the Rust repo for a plain-text
version.

And don't forget to update the license metadata in your Cargo.toml to:

license = "MIT OR Apache-2.0"

I'll be going through projects which agree to be relicensed and have approval
by the necessary contributors and doing this changes, so feel free to leave
the heavy lifting to me!

Contributor checkoff

To agree to relicensing, comment with :

I license past and future contributions under the dual MIT/Apache-2.0 license, allowing licensees to chose either at their option.

Or, if you're a contributor, you can check the box in this repo next to your
name. My scripts will pick this exact phrase up and check your checkbox, but
I'll come through and manually review this issue later as well.

• @kbknapp
• @cburgdorf
• @Ryman
• @tak1n
• @orclev
• @kentcdodds
• @killercup
• @PascalPrecht
• @gitter-badger

Stash and github are largely compatible but differ in very slight ways. It would be nice if clog could generate links not only for github, but also for stash. In order to support this there should be an option to provide the flavor of repository links should be generated for.

I've implemented this in a fork and can do a pull request assuming you don't have any changes you want me to implement. My current implementation adds a new CLI parameter --repoflavor and a TOML option repo-flavor, both of which accept either "github" or "stash" as arguments (case insensitive). This new parameter controls two aspects of the changelog generation. Firstly it changes the commit links to follow the proper convention for the respective repository flavor. Secondly it changes the issue links to not be generated in the case of stash (because it doesn't have built in issue tracking). This approach is flexible and it should be relatively trivial to add support for other kinds of repository flavor down the line (bitbucket maybe?).

This would then automatically look up the latest tag and increment accordingly

Couldn't find any tests in the source yet (if there are any, please point me to them). Is there already a convenient way of writing (unit) tests for Rust libraries?

A nice project that popped recently in my twitter timeline. It's a CLI tool that helps you writing commit messages that follow conventions. I think it'd be nice to add it to the readme as companion tool.

Here's a link: http://commitizen.github.io/cz-cli/