Change log strategy

[MattHJensen]

In #723, we are constructing a change log for 0.6.2 -> 0.6.3 by reviewing our commits over the intervening period. This might not be the best strategy going forward as it requires good memories or detective work or both. This issue is meant for discussion of how to track changes in the future.

Examples of change logs include those of the Policy Simulation Group, SQLite, Bokeh, and Python.

[martinholmer]

How about adding to the release change log as we go? See issue #841.

[MattHJensen]

How about adding to the release change log as we go? See issue #841.

That makes sense to me.

Where do you think it would make sense to document this procedure for other contributors?

[martinholmer]

Martin said:

How about adding to the release change log as we go? See issue #841.

Matt responded:

That makes sense to me.

Where do you think it would make sense to document this procedure for other contributors?

Well, a few months ago I would have said the Contributor Guide, but now I'm not so sure. There isn't much evidence that new users are reading it. See, for example, open pull request #824 submitted by codykallen. First of all, this person is not even a GitHub user --- at least, that name does not come up when I type @cod. And, he doesn't seem to have read the Tax-Calculator README.md file, which says to read the Contributor Guide and to read the TESTING.md documents. So, I'm not sure investing a lot more time in these documents will make much difference.

[MattHJensen]

First of all, this person is not even a GitHub user --- at least, that name does not come up when I type @cod.

This is because I haven't added Cody to the Open-Source-Economics organization. I will do that now.

[MattHJensen]

and he doesn't seem to have read the Tax-Calculator README.md file, which says to read the Contributor Guide and to read the TESTING.md documents. So, I'm not sure investing a lot more time in these documents will make much difference.

The content in these documents have been very helpful for new contributors and TC users in the past, but I have the same sense as you that people aren't finding it by themselves. If we agree that the content in these docs is helpful and that there is, in fact, even more content we want contributors to see, then I see three options:

1. Do a better job of manually pointing people to the content.
2. Make links to the content more visible.
3. Put the content in a new place (GH wiki or similar).

None of these feels like a golden bullet, though. Any other ideas?

cc @talumbau, @Amy-Xu, @zrisher, @GoFroggyRun

[feenberg]

On Fri, 5 Aug 2016, Matt Jensen wrote:

  and he doesn't seem to have read the Tax-Calculator README.md file, which
  says to read the Contributor Guide and to read the TESTING.md documents.
  So, I'm not sure investing a lot more time in these documents will make
  much difference.

The content in these documents have been very helpful for new contributors and TC
users in the past, but I have the same sense as you that people aren't finding it by
themselves. If we agree that the content in these docs is helpful and that there is,
in fact, even more content we want contributors to see, then I see three options:

1. Do a better job of manually pointing people to the content.
2. Make links to the content more visible.
3. Put the content in a new place (GH wiki or similar).

None of these feels like a golden bullet, though. Any other ideas?

The documentation needs a web page, github won't do. In fact, the project
needs a couple of web pages and should not depend on github for anything
other than source code control and ticketing. It isn't a good interface
for users of the software to learn about it.

dan

cc @talumbau, @Amy-Xu, @zrisher, @GoFroggyRun

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub, or mute the
thread.[AHvQVZdF4YLsUVsI7Cr5-ZJoq1wZJHFVks5qdBd9gaJpZM4IXcda.gif]

[MattHJensen]

In fact, the project needs a couple of web pages and should not depend on github for anything other than source code control and ticketing.

What do you see as the high priorities as far as content go?

[zrisher]

The documentation needs a web page, github won't do. In fact, the project
needs a couple of web pages and should not depend on github for anything
other than source code control and ticketing. It isn't a good interface
for users of the software to learn about it.

@MattHJensen @feenberg I actually disagree, github was designed to facilitate easy contribution by people unfamiliar with a software project (just look at their About page). Github provides web pages, and offhand I can't think of any cases where a fully customizable web page provides significant advantages over writing your documentation in markdown or using a repo's wiki. Perhaps we can think of some ways in which our own web pages would provide superior documentation support?

I've used it for a long time, so I'm probably biased by familiarity. But I do think that indicates an advantage - anyone used to contributing to projects on Github will find it easy to navigate the documentation of any other repo.

Regarding the change log question - you don't know for sure if your commit/PR will be included in a release when you're writing it. The only person who knows that is the manager of the release when they're finalizing the release. Commit and PR messages are designed to quickly summarize their contents. I think the most logical process is to simply review the included PRs and commits when constructing the change log. If you have to look through the commit files to figure out what happened, I think that indicates a problem with the commit message or PR documentation.
@martinholmer @talumbau

[feenberg]

On Sat, 27 Aug 2016, zrisher wrote:

  The documentation needs a web page, github won't do. In fact, the
  project needs a couple of web pages and should not depend on
  github for anything other than source code control and ticketing.
  It isn't a good interface for users of the software to learn about
  it.

@MattHJensen @feenberg I actually disagree, github was designed to
facilitate easy contribution by people unfamiliar with a software project
(just look at their About page). Github provides web pages, and offhand I
can't think of any cases where a fully customizable web page provides
significant advantages over writing your documentation in markdown or using
a repo's wiki. Perhaps we can think of some ways in which our own web pages
would provide superior documentation support?

I've used it for a long time, so I'm probably biased by familiarity. But I
do think that indicates an advantage - anyone used to contributing to
projects on Github will find it easy to navigate the documentation of any
other repo.

Personally, I find github very off-putting and not something that
economsits or policy types will be familiar with, or want to learn about.
In practice, they may think "Oh, this sofrware is still in early stages of
development - maybe I'll come back when they are far enough along to have
a web page."

It is one thing to go to github to download a .tar.gz of a binary - but
Github is not a way to "market" a new and complicated package to a
possibly skeptical audience. A website doesn't need to be fancy, but it
needs links to documentation that lead to online html, not a zip file.

We also need a mailing list about users questions and taxes, not patches.

daniel feenberg

[zrisher]

Since the discussion on our general documentation needs and mailing list are complex and not entirely instructive on "how should we track changes to the repo?", I've moved them to #891 and #892 respectively. @MattHJensen I hope that's OK.

[martinholmer]

What is the status of issue #724 with respect to "change log strategy"?
We seem to have settled on such a strategy (see issue #1058, for the most recent example).
Given that, is there any reason to keep #724 open?

@MattHJensen @feenberg @zrisher

[MattHJensen]

We seem to have settled on such a strategy (see issue #1058, for the most recent example).
Given that, is there any reason to keep #724 open?

I don't think so. Closing.