Add --base option

[raphink]

For projects migrating to an automatically generated CHANGELOG, it is useful to keep the old changes in a base file that is appended, so this can be used like this (considering the migration happened after tag 0.1.15):

github_changelog_generator --future-release 0.2.0 --since-tag 0.1.15 -b CHANGELOG.base.md 

where CHANGELOG.base.md contains changes up to the 0.1.15 tag.

Note: --since-tag is implemented in #257

[skywinder]

@raphink 👍 👍 👍 👍
Simple and awesome solution!
It serve as good workaround for #71, and also help to resolve in the future #209 and #211

[skywinder]

It would be nice if you also add description from this PR body to README.md : how to migrate from manually-added change logs files to auto-generated change log to faq section with one more bullet like:

• I already have manual change log. How can I migrate to auto generated change log?

[skywinder]

just kind proposal: Can you add basic tests for this option? (only if you know how, and it's not burden you)

[raphink]

Right, I will check these.

I'm actually wondering if since_tag could be made automatic when base is set. In that case, users would be encouraged to convert their old CHANGELOG into github-changelog-generator's format (which is a good idea anyway so that it looks homogeneous) and the lib could parse the top entry to retrieve the last manually managed tag, using it as since_tag. Any thoughts on that?

[raphink]

As for the tests, are you thinking of adding a fixture for that, or just mocking File.read?

[skywinder]

I believe fixture would be better ( in manner as it implemented for change
log reader.rb tests, that @estahn kindly provided. )

About auto detection of the end manual change log - you just read my minds!

Here`s some ideas that comes to my head about this:

1. To find last tag in manual change log file we can use reader.rb
   module. Implement Reader class to parse ChangeLog.md #216
2. to not set every time since-tag - we can just put at first time, (when
   since tag specified) some "magic" string, that will be invisible in
   markdown, but helps us to detect end of manual change log next time.
3. We can also try to detect base change log file ( if it`s not defined)
   • --output option
   • standard cnglg names such as CHANGELOG & HISTORY.md

And thanks again for getting move this project forward! 🍻

[raphink]

I'll have a look at these tomorrow then.

[raphink]

Added an entry in README.md and automatic support for HISTORY.md

[skywinder]

@raphink Great addition, thanks again! ! Please, check the failed tests in last commit.
Then I will merge your PR and add some tests for this feature.

[raphink]

I'll try to review that. Are you OK with the implementation?

[skywinder]

Yes, implementation seems good!
As I said, I would like to improve detection in the future by adding "magic" string. But I think, it's better to implement such feature in next release.

[raphink]

Fixed the tests

[skywinder]

Awesome work! Thank you, @raphink!

[skywinder]

@raphink I found, that some guys also using Unreleased tag. In that case --base works incorrect and gets:

Warning: can't find tag Unreleased, specified with --since-tag option.

I'm not sure, that we have to do something with it, since it can be easily solved by manually specify --since-tag, just want to know your thoughts about this case.

Example:

github_changelog_generator troessner/reek -b CHANGELOG.md

[skywinder]

@raphink another thing about --base option:

If you run

github_changelog_generator troessner/reek  -b CHANGELOG.md --since-tag v3.3.0

it gets list of all issues under Unreleased section. And then old change log. I believe it's not what user expect to see.

[raphink]

You mean people use Unreleased as the top entry in HISTORY.md?

[skywinder]

@raphink Yes. You can try, how it works on real repo:

git clone https://github.com/troessner/reek && cd reek && github_changelog_generator troessner/reek  -b CHANGELOG.md --since-tag v3.3.0 && open CHANGELOG.md

[raphink]

So what should be expected then?

• Remove "Unreleased" from the top of the file and append the entries (this might lead to duplicate entries, very likely)
• Ignore the Unreleased entry altogether and append the rest of the base file

[skywinder]

The additional sections is not main problem - it could be fixed easily with --since-tag v3.3.0
The main issue there that changelog in that case became unstructured. Because in that case all issues comes in one section and then printed old manual. So it lose all structure of change log.

[raphink]

I guess it's just not a good idea to use incremental and unreleased together.

Incremental with releases should work well, though.

[skywinder]

@raphink What you mean under "Incremental" term?

[raphink]

I mean using an already generated changelog as a base for a new one, so only new tags are generated.

[skywinder]

Ok, got it. with the fix #267 it should work fine.
But I' thinking about advanced logic for this option.
Please, check #269 with for details. I will be glad to hear any ideas/suggestions.