[Suggestion] Add a HISTORY.rst file

[JacobCallahan]

Hi team, As we all know, Robottelo is a fairly large automation project, with many people working on it at the same time. This makes it difficult to track changes that everyone should be aware of. With that in mind, I'd like us to add something like a HISTORY.rst file to note these changes as they are introduced. Hypothetical Example: I just introduced a change to our container creation, switching from docker to podman and requiring an additional parameter. The history entry could look something like this.

6/26/2019
---------
  + Changed container runtime from docker to podman
  + BREAKING CHANGE: 'create_container' method now requires a 'use_root' argument
...

Again, that is just an example so formatting/message standards don't have to follow. I'd like to hear your thoughts and suggestions for something we can use in-repo to this effect.

Edit for clarification: The HISTORY.rst update should be in the commit that introduced the change.

[JacobCallahan]

One likely issue of having each person updating the history file is merge conflicts since multiple people could be updating the same file at once. Once we get the stable branch changes going, then the person updating the stable branch could collate changes into the history file.

[latran]

A couple of questions come to mind when using a history file.

1. Are these applicable for ALL changes, both minor and major?
2. Potential thousands of changes being tracked in a file. How long of a list of changes should be kept? Indefinitely? A couple of years?
3. Tracking changes of changes. How would that work? Let's say I did major changes on Thing A. Then someone looks at it months later and decides to update changes in Thing A. Should that person update the file underneath my Thing A or create a new line for that update? Basically how should updates on those old changes be referenced? (This is mainly for readability).

These are just some thoughts I had.

[JacobCallahan]

1. These should only be changes that introduce new functionality or change existing functionality in a way that other people should know about. This is pretty subjective right now, but we can develop some standards as we go.
2. That's a good question. We'd likely have to assess based on the rate of additions we're seeing.
3. No. This should read like a ledger, but from newest to oldest. If someone changes Thing A after you, then they would add a new entry at the top of the file.

[latran]

Ok good to know. I'm all for this experimental idea that would potentially be a permanent addition to our processes. We can improve along the way as we see fit.

[flatfender]

+1 to this idea

[ntkathole]

What about creating it with automated way [1]. We can modify it and pick up only required commits as per commit message.

History
=======

GitHub Log
----------

* Jun 26, 2019
    - (by: Lai Tran) 
        - Merge pull request #7051 from swadeley/realm-metadata
            Update metadata for realm CLI tests
    - (by: vsedmik) 
        - CaseComponent updated according to test purpose.
* Jun 25, 2019
    - (by: vsedmik) 
        - Tier and Requirement fix.
* Jun 24, 2019
    - (by: vsedmik) 
        - Metadata cleanup
* Jun 25, 2019
    - (by: ntkathole) 
        - Remove docker compute resource CLI test cases

[1] https://gist.github.com/ntkathole/cb8d091a04e35ecd4922356d6e25b800

[JacobCallahan]

@ntkathole I'd like it to be less noisy and more helpful than a gitlog can provide. Not every commit will need a new history entry. I'm betting most won't. Also, I'd like the entries to be better than most of our commit messages, plus a bit of elaboration would be great!

[mirekdlugosz]

My main concern revolves around implicit assumption of certain knowledge about specific point in past.

Changelog entry is tool to update mental model. It can be effective in pretty much only one case - when my model is slightly outdated. Reading changelog will get me up to speed. If my model is highly outdated (I go back to framework after long break), finding place when I dropped off and going through all updates is not effective. It's faster to just learn what is the current state of things (by reading current documentation or code). If my model is non-existent (I am new contributor), changelog is completely useless. I would have to first learn how things were. Again, it's better to just learn what is the current state of things. If my model was wrong to begin with (I though framework works like that, while it does not), changelog might help me realize I need to revise it. But again - I am probably better off just reading current documentation or code.

Changelog could be a platform to advertise capabilities of framework while they are new. But the same goal can be achieved by code review - when you see someone does not use a tool they could, you can ask if they know about feature XYZ and why they didn't use it. Might turn out they weren't aware it exists.

Then there is semi-theoretical concern that we might simply fail to fully realize consequences of the change that is introduced. So some breaking changes do not enter changelog at all.

---

Personally, I would rather have us focus on better commit messages. If the problem is that we collectively lack knowledge and skill in git, we should invest in training - it will pay off much better than any process change could.