Limiting the effect of regressions and informing about workarounds

[aspiers]

(The original title was: "please re-introduce the NEWS file and maintain intra-release". Changed by @tarsius because that no longer is the only focus of this discussion.)

---

In #675, @tarsius commented:

Since we are also moving rebase-mode outside the magit repository it
makes little reason to go all crazy about phasing out
magit-log-edit.el gracefully. Some people (who don't use package.el)
might end up without rebase-mode and/or a commit mode for a
while. Since that "only" means that they lose the font-locking and
some convenience key bindings, this is acceptable. They can edit the
commit messages and rebase instructions using fundamental-mode until
they have figured out where to get the dependencies (e.g. by looking
at the release notes).

Unfortunately there are no release notes, so this caused me quite some pain until I waded through several lengthy pull requests to understand why updating to the latest git broke a lot of things. I probably do rebase -i via magit between 20 to 50 times every day, so losing the key bindings makes a big difference for me. I figured out how to get them back, but it took quite a bit of time.

Likewise the switch to git-commit-mode confused the hell out of me ...

Maybe I deserve breakage by running from master rather than waiting for a stable release, but I think it would be much better if the NEWS file was re-introduced (yes, it used to exist), and then maintained to be more or less correct with each commit, so that anybody who wants to join development at any time can quickly get up to speed with the latest stuff which is being worked on for the next release. Release notes have to be written anyway, so it's no extra work, and maybe even easier to do incrementally than having to write them from scratch just before each release.

Thanks for listening, and for your great work on magit!

[dudebout]

I would vote to keep it outside of the git repository. More like a wiki
page which can reference pull requests etc.
On Aug 24, 2013 8:01 PM, "Adam Spiers" notifications@github.com wrote:

In #675 #675, @tarsiushttps://github.com/tarsius
commentedhttps://github.com//issues/675#issuecomment-22561681
:

Since we are also moving rebase-mode outside the magit repository it
makes little reason to go all crazy about phasing out
magit-log-edit.el gracefully. Some people (who don't use package.el)
might end up without rebase-mode and/or a commit mode for a
while. Since that "only" means that they lose the font-locking and
some convenience key bindings, this is acceptable. They can edit the
commit messages and rebase instructions using fundamental-mode until
they have figured out where to get the dependencies (e.g. by looking
at the release notes).

Unfortunately there are no release notes, so this caused me quite some
pain until I waded through several lengthy pull requests to understand why
updating to the latest git broke a lot of things. I probably do rebase -ivia magit between 20 to 50 times every day, so losing the key bindings
makes a big difference for me. I figured out how to get them back, but it
took quite a bit of time.

Likewise the switch to git-commit-mode confused the hell out of mehttps://groups.google.com/d/msg/magit/ByE2qMC12hM/mAnJWmhhkwoJ...

Maybe I deserve breakage by running from master rather than waiting for a
stable release, but I think it would be much better if the NEWS file was
re-introduced (yes, it used to existhttps://github.com/magit/magit/commit/51dc5d9#diff-3),
and then maintained to be more or less correct with each commit, so that
anybody who wants to join development at any time can quickly get up to
speed with the latest stuff which is being worked on for the next release.
Release notes have to be written anyway, so it's no extra work, and maybe
even easier to do incrementally than having to write them from scratch just
before each release.

Thanks for listening, and for your great work on magit!

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/807
.

[tarsius]

+1 for a page on the wiki. I don't want this to be a off-site "NEWS" file though.

We should not announce new features there. The focus should be on informing users about regressions and available workarounds. As well as about changes that intentionally affect existing features; with a link to the relevant discussion.

New features shouldn't be announced there because such features often are still subject to major changes, and the purpose of the page is to help users deal with problems, not to let them know of additional ways to get into trouble.

The new page should be more of a "FAQ for current issues" than a classical NEWS file. We might call it NEWS though or we could just add a "current issues" section to the existing FAQ. We also have to add links from the README, the wiki index and the homepage. And if we actually create a new file between that and the existing FAQ, which by the way is more of a stub at the moment.

We might also want to use twitter for breaking news. I would prefer using rss though - but that might be more work to setup.

All of this might not sound like a lot of work but it is. I have avoided doing it because even though I have made many big changes over the last few months we never had any major problems affected a large portion of our users. And when I did break something I usually fixed it within a few days at most. However I intended to switch to a safer release model once 1.3.0 is out.

@dudebout Could you please take care of the wiki page(s) and the links (and possibly twitter/rss). We also have to update the homepage, it contains false statements.

I am "a bit" overworked right now cleaning up the breakage resulting from our premature switch to git-commit-mode. So I cannot possibly do this myself (but you might also want to wait until we have talked over skype).

---

@aspiers You are quoting me out of context. That is understandable; as a user I wouldn't have read the hole thing after the fact either.

I have actually argued all along (going back several months) that we should take extra precautions not to break anything. The passage you are quoting is when I finally folded because everyone else argued that playing it safe was not necessary and would just cause me more work.

There were many unknowns and for that reason we should have ensured that there was an easy to use fallback available. My wording in the passage you quote was imprecise: I meant "the only thing I expect to actually happen to some users" not "the worst case scenario".

---

Well we pretty much hit the worst case scenario. Which is very unfortunate; it would not have happened had I followed my instinct instead of folding due to overwhelming opposition. Doing that would have saved users from having to get involved to be able to use fundamental magit features again. It would also have saved me a lot work writing ugly emergency fixes. I estimate that the release of 1.3.0 has to be pushed back by at least two weeks because of this.

On the plus side this will serve as motivation to do more subminor and minor releases, and to base the melpa package on the maint branch. (I intended to do that regardless of this issue, but this certainly gives me a strong argument.) I will elaborate on that later - back to fixing server/client interaction.

[dudebout]

@tarsius I'll do it.
On Aug 25, 2013 1:09 PM, "Jonas Bernoulli" notifications@github.com wrote:

+1 for a page on the wiki. I don't want this to be a off-site "NEWS" file
though.

We should not announce new features there. The focus should be on
informing users about regressions and available workarounds. As well as
about changes that intentionally affect existing features; with a link
to the relevant discussion.

New features shouldn't be announced there because such features often are
still subject to major changes, and the purpose of the page is to help
users deal with problems, not to let them know of additional ways to get
into trouble.

The new page should be more of a "FAQ for current issues" than a classical
NEWS file. We might call it NEWS though or we could just add a "current
issues" section to the existing FAQ. We also have to add links from the
README, the wiki index and the homepage. And if we actually create a new
file between that and the existing FAQ, which by the way is more of a stub
at the moment.

We might also want to use twitter for breaking news. I would prefer using
rss though - but that might be more work to setup.

All of this might not sound like a lot of work but it is. I have avoided
doing it because even though I have made many big changes over the last few
months we never had any major problems affected a large portion of our
users. And when I did break something I usually fixed it within a few days
at most. Instead I intended to just switch to a safer release model once
1.3.0 is out.

@dudebout https://github.com/dudebout Could you please take care of the
wiki page(s) and the links (and possibly twitter/rss). We also have to
update the homepage, it contains false statements.

I am "a bit" overworked right now cleaning up the breakage resulting from
our premature switch to git-commit-mode. So I cannot possibly do this

myself (but you might also want to wait until we have talked over skype).

@aspiers https://github.com/aspiers You are quoting me out of context.
That is understandable; as a user I wouldn't have read the hole thing after
the fact either.

I have actually argued all along (going back several months) that we
should take extra precautions not to break anything. The passage you are
quoting is when I finally folded because everyone else argued that playing
it safe was not necessary and would just cause me more work.

There were many unknowns and for that reason we should have ensured that
there was an easy to use fallback available. My wording in the passage you
quote was imprecise: I meant "the only thing I expect to actually happen to

some users" not "the worst case scenario".

Well we pretty much hit the worst case scenario. Which is very
unfortunate; it would not have happened had I followed my instinct instead
of folding due to overwhelming opposition. Doing that would have saved
users from having to get involved to be able to use fundamental magit
features again. It would also have saved me a lot work writing ugly
emergency fixes. I estimate that the release of 1.3.0 has to be pushed back
by at least two weeks because of this.

On the plus side this will as motivation to do more subminor and minor
releases, and to base the melpa package on the maint branch. (I intended to
do that regardless of this issue, but this certainly gives me a strong
argument.) I will elaborate on that later - back to fixing server/client
interaction.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/807#issuecomment-23231372
.

[tarsius]

@dudebout I have updated some outdated information on the homepage. The wording could still use some love. Let's talk about the mailman thing face to face.

[dudebout]

@tarsius I am not convinced that we should do twitter/RSS integration. I would consider making the wiki page very accessible so that people realize it is a useful resource to use when magit does not work. I have created the page https://github.com/magit/magit/wiki/Known-issues. However, I am not fully up to date with the current issues and workarounds. I will put in what I can find from the issues.

[aspiers]

Thanks a LOT for listening and reacting to my concerns! However, sorry to sound negative but I would like to place a definite vote against using the wiki for the following reasons:

1. All the information we are discussing is strongly coupled to a particular revision or release of the source code, therefore it belongs in the same branch of the repository as the code which it is referring to. If you use the wiki, then the information can either only refer to one specific version (e.g. the most recent release, or the tip of the main development branch), in which case it's inaccurate and misleading for all other versions, or it has to refer to multiple versions, in which case the page becomes bloated and confusing to read.
2. Information placed in the wiki is unavailable offline. E.g. if I upgrade magit via el-get-update or similar just before going on a train / plane, I would have the whole repository available on my laptop but none of the critical information about things in the new version which might bite me.
3. Keeping any such information on the wiki lowers the expectation for contributors to update it in accordance with any code changes they make. If all docs are together with the code in the git repo, it's easy for maintainers to reject pull requests on the grounds that they don't update the corresponding documentation. If they are splintered off in the wiki, often contributors will not even realise that there is the possibility their pull request may have an impact on the wiki too. Even if they do realise, this places a burden on either the contributor to remember to update the wiki should the PR be accepted, or on the maintainer to update it after accepting the PR.
4. Wiki changes are not subject to the pull request process, so structured peer review is not possible.
5. I see no advantages to using the wiki - especially since github introduced relative linking in repos, e.g.:

• https://help.github.com/articles/relative-links-in-readmes
• https://github.com/blog/1395-relative-links-in-markup-files

In summary, putting docs in the wiki is IMHO a mistake which I have seen many projects make (including my own ;-) Please don't join that list ;-)

Thanks again for your great work!

[PureAbstract]

I'd like to add a '+1' to @aspiers comments - I think that release notes/NEWS etc belong in the main repo for exactly the reasons he mentions.

The reality is that the only golden source of truth in any software project is the source code itself - reality supertrumps documentation every time.

[tarsius]

putting docs in the wiki is IMHO a mistake

Maybe. Right now I am being bombarded with new issue and pull requests. (1. Well we. 2. Some related to the commit breakage but not all. It's definitely a good thing but why is it happening now? Because I merely stated that I want to put a focus "on community building"? That would be great but it's also a bit of a problem for me that it is happening right now.)

I appreciate your points. I am a bit overworked and haven't found the time to give this any serious thought yet. I don't want to move the faq/known issues before the release. I feel comfortable doing quick brain dumps to the wiki than to the source repository. For more I don't have the time, have to focus on fixing.

While you are making some good arguments I think the "anybody can contribute on the wiki" argument is also a good one. Of course we could also have users edit the wiki and then merge into the bundled version.

sorry to sound negative

Np. Your are making good point and the criticism is constructive.

Actually this kind of detailed discussion of (potential) problems is exactly what I hoped for when I made "the final call for objections" regarding moving to git-commit-mode. Unfortunately you didn't see that in time.

[aspiers]

Right now I am being bombarded with new issue and pull requests. [...] It's definitely a good thing but why is it happening now?

I accept the blame for a lot of the bombardment ;-) It's simply because I used (and loved) magit for a long time, and after randomly upgrading to latest git master, stuff changed in a way I didn't understand which got me scared that maybe magit was being taken in a new direction very different to what I need. And I am the kind of pain in the ass guy who speaks up when he thinks something might be going wrong ;-)

But then I looked more closely into the details and found that no, magit is still in good hands and going in the right direction, but I was just unlucky enough to upgrade at the wrong time when it was midway through a big transition. So please don't feel stressed or worried by my bombarding. I have confidence that the issues will be fixed in good time, and meanwhile magit is working plenty good enough for me, so I am happy to wait. The last thing I want is for you to burn out when you are doing a good job!

Despite my objections to using the wiki, it's fine as a short term solution, so please exercise your own judgement when prioritising things rather than letting me pressure you into something which feels wrong for you. I just think it's not the right long-term solution for all the reasons I listed.

Actually this kind of detailed discussion of (potential) problems is exactly what I hoped for when I made "the final call for objections" regarding moving to git-commit-mode. Unfortunately you didn't see that in time.

Yeah, sorry ;-/ I had no idea any of this was happening until I randomly upgraded and then joined the community in order to understand what was going on.

[aspiers]

By the way, 6655c0c is a huge step in the right direction, so thanks for that!

[tarsius]

And I am the kind of pain in the ass guy who speaks up when he thinks something might be going wrong ;-)

No problem here. I appreciate that. And I also prefer your long form posts (which I also often practice). It appears github issues somehow discourage that - another reason to make better use of the mailing list.

I randomly upgraded and then joined the community in order to understand what was going on.

And that is only one of the positive things that has come out of this :-)

[PureAbstract]

It appears github issues somehow discourage that

I've always put that down to the 4-line default edit field (I sometimes wonder how many people know what the 'Zen Mode' icon does...)

[dudebout]

@aspiers, here is my promised answer to your points. Generally I believe we are talking about two different ideas. I was thinking of having a place that can point people to all the current issues and pull requests related to a specific issue. Github does not really provide this kind of grouping at the moment. As such, I really envision some temporary information. The goal is to help people with problems understanding what is currently being investigated. This information is "on the same level" as the comments we post on github which are not part of the repository.

I do not think that discussion about current problem should be commited to the repository. It would mean, that as new PR and issues are opened and someone figures out what is going on, that new commits would be made with just discussion content.

I might just not be able to understand what you envision exactly. Maybe you could take the current git-commit-mode problem, and write what you envision for this NEWS file. It might be easier to discuss a concrete example.

[aspiers]

Generally I believe we are talking about two different ideas. I was thinking of having a place that can point people to all the current issues and pull requests related to a specific issue. Github does not really provide this kind of grouping at the moment.

Actually it does. Any time you reference one issue or pull request from another issue or pull request, github automatically adds a hyperlink between the two. What more is needed?

As such, I really envision some temporary information. The goal is to help people with problems understanding what is currently being investigated. This information is "on the same level" as the comments we post on github which are not part of the repository.

If they want this information, they can simply browse the github issue tracker. We should not duplicate this information elsewhere, because it will immediately become out of sync with the tracker and as a result misleading.

I do not think that discussion about current problem should be commited to the repository.

I don't either. I never proposed committing discussion to the repository.

It would mean, that as new PR and issues are opened and someone figures out what is going on, that new commits would be made with just discussion content.

Right, that would be crazy ;-)

I might just not be able to understand what you envision exactly. Maybe you could take the current git-commit-mode problem, and write what you envision for this NEWS file. It might be easier to discuss a concrete example.

We already have concrete examples:

• https://github.com/magit/magit/wiki/FAQ
• https://github.com/magit/magit/wiki/Known-issues

I am simply saying that these should live in the repo, not the wiki, due to the 5 reasons I already listed.

[dudebout]

The grouping offered by github does almost nothing. You do not see it from outside the PRs or issues. It does not offer a good view to someone having a problem trying to figure out if other have the same one. The grouping offered in the known issues wiki page is what is needed.

I explicitely want something better than the issue tracker. The issue tracker is bad for someone that is not following the project. Every user experiencing the breakage should waste time figuring which issues are related. That does not make sense as maintainer already have this information so they can just write it down.

Finally, let's look at the current concrete example you gave. The known issues wiki page is of little use without access to github. It would be weird to have this file inside the source repository in my opinion.

Here is why I think your 5 reasons do not really apply to this kind of files:

1. I envision only talking about the current breakages not a long lived file. There is no real risk of bloating
2. Irrelevant since you need to be online to figure out if other people have the same problem
3. The current breakages is not to be updated by every contributors. It is more a maintainer tool as they have the knowledge of the current status.
4. This is not something that needs to be perfect, just helpful to figure out the current broken parts
5. This only works while on github. What happens when you are in a train/plane as in 1?

[aspiers]

The grouping offered by github does almost nothing. You do not see it from outside the PRs or issues. It does not offer a good view to someone having a problem trying to figure out if other have the same one. The grouping offered in the known issues wiki page is what is needed.

I agree that the list of known issues is essential to have.

I explicitely want something better than the issue tracker. The issue tracker is bad for someone that is not following the project. Every user experiencing the breakage should waste time figuring which issues are related. That does not make sense as maintainer already have this information so they can just write it down.

Again, I agree. Remember, it was me who filed this issue :-) I'm not sure why you are trying to persuade me of something which I already asked for.

Finally, let's look at the current concrete example you gave. The known issues wiki page is of little use without access to github.

I strongly disagree. It's of great use without github. Why do you say that?

It would be weird to have this file inside the source repository in my opinion.

Why? It's very common for projects to include a known issues document inside the repo.

Here is why I think your 5 reasons do not really apply to this kind of files:

1. I envision only talking about the current breakages not a long lived file. There is no real risk of bloating

I think you misunderstood my point. Please read 1. again. It's not just about whether the doc gets bloated or not, it's about whether it contains misleading information. Your reference to "current breakages" implies that you are only thinking about master, but we also have to think about people running older / more stable branches. The set of known issues for master is different to the set for a stable release. So if the doc is in the wiki, you have to cover all versions, and this makes it hard to present the information in a clean way.

1. Irrelevant since you need to be online to figure out if other people have the same problem

Huh? You figure out whether other people have the same problem by reading the known issues doc. If this is in the repo, you don't need to be online.

1. The current breakages is not to be updated by every contributors.

Not every contributor, but the more that help, the less the burden on the maintainer.

It is more a maintainer tool as they have the knowledge of the current status.

It's not just the maintainer who has knowledge of the current status. Why are you trying to make his job harder?

1. This is not something that needs to be perfect, just helpful to figure out the current broken parts

I didn't say it needs to be perfect. But that's not a good reason to avoid peer review.

1. This only works while on github.

Not necessarily, e.g. you can generate HTML from the MarkDown.

What happens when you are in a train/plane as in 1?

You generate HTML, or simply manually open the linked file.

[afrepues]

I think it will be useful to distinguish between release files and repository.

• Do we want the list of known issues in a release package (either tar or package.el)?

  I think is useful, we should have it. Also, it is easy to generate automatically at build time.

• Do we want to have this into the repository?

  I would not put it, it duplicates the information already in the issue tracker, would adds commits to history that are superfluous to the code history, and will need work to keep up to relevant.

I think that using a release tag for the tickets affecting a given release will do the trick. It does need work, but work will be needed with a wiki page or a file in the repository that need to be updated manually. When building the package the list of open issues for the current release version could be pulled and included in a file (e.g.: KNOWN-ISSUES, or just somewhere in the README).

[dudebout]

@afrepues I think this is a really helpful distinction.

[aspiers]

I think it will be useful to distinguish between release files and repository.

Do we want the list of known issues in a release package (either tar or package.el)?

I think is useful, we should have it.

I agree.

Also, it is easy to generate automatically at build time.

If you generate it automatically, it won't be anywhere near as useful. Look at the existing Known Issues wiki page. It's a really useful summary of all known issues, grouped in sections, with brief explanations / background. There is no way to automatically generate that. If you generate a list of issue numbers and titles, it would be much less useful, because the issue titles have to be short, and are consequently often necessarily cryptic.

Do we want to have this into the repository?

Bearing in mind that it cannot be automatically generated without significant loss of quality, there are only two places to put it: the repository, or the wiki (where it is now). I have already explained (twice) the five advantages of putting it in the repository.

I would not put it, it duplicates the information already in the issue tracker

To say that it duplicates that info misleadingly implies that would be a bad thing. It presents a different view of the same information, which is useful in different circumstances.

would adds commits to history that are superfluous to the code history

"Superfluous" is defined as "being more than is sufficient or required; excessive". What's your logic for describing it this way? Are commits to tests and documentation superfluous? No. And this is just another type of documentation.

and will need work to keep up to relevant.

Of course; that's true of anything in this context.

I think that using a release tag for the tickets affecting a given release will do the trick. It does need work, but work will be needed with a wiki page or a file in the repository that need to be updated manually. When building the package the list of open issues for the current release version could be pulled and included in a file (e.g.: KNOWN-ISSUES, or just somewhere in the README).

Again, you seem to be assuming that a simple list of issue numbers / titles (and maybe descriptions, or extracts thereof) is sufficient. It is not.

[afrepues]

If you generate it automatically, it won't be anywhere near as useful. Look at the existing Known Issues wiki page.

Will it will depend on the quality of the wording of the issues? Of course! But that is a good reason to try to enhance the information is put in them.

It's a really useful summary of all known issues

I think this is the best description of the document we need to include.

, grouped in sections, with brief explanations / background. There is no way to automatically generate that.

Use any tag that is not marking the release(s) the bug applies to as categories for grouping.

If you generate a list of issue numbers and titles, it would be much less useful, because the issue titles have to be short, and are consequently often necessarily cryptic.

Not necessarily, and for those cases you have the option of manual post-processing of the generated document.

I would not put it, it duplicates the information already in the issue tracker
To say that it duplicates that info misleadingly implies that would be a bad thing. It presents a different view of the same information, which is useful in different circumstances.

Different view, same content, has to be synchronized with any changes to the issue anyways, hence: duplication, more effort.

"Superfluous" is defined as "being more than is sufficient or required; excessive". What's your logic for describing it this way? Are commits to tests and documentation superfluous? No. And this is just another type of documentation.

This is a release artifact, not a source artifact. Does it history add anything to the understanding of the source? No, hence, superfluous.

Again, you seem to be assuming that a simple list of issue numbers / titles (and maybe descriptions, or extracts thereof) is sufficient. It is not.

Well, but it doesn't need to be a work at Shakespeare level, does it? It needs to be non-ambiguous, up-to-date, easy to read and understand.

[aspiers]

, grouped in sections, with brief explanations / background. There is no way to automatically generate that.

Use any tag that is not marking the release(s) the bug applies to as categories for grouping.

That would partially solve the grouping aspect. It would still not be able to automagically brief explanations and background context out of thin air. Or maybe you have code which can automatically generate prose which passes the Turing test? In which case I suggest you publish your invention immediately, earn a Nobel Prize, and retire ;-)

If you generate a list of issue numbers and titles, it would be much less useful, because the issue titles have to be short, and are consequently often necessarily cryptic.

Not necessarily

Necessarily, unless you are suggesting that it's acceptable for issue titles to be longer than about 10 to 15 words... which it isn't ;-p

and for those cases you have the option of manual post-processing of the generated document.

That wouldn't work well at all, because manual editing would be required after every generation of the document. This would cause extra work for the maintainer, and also increase the likelihood of the known issues document changing more than it needed to every release.

I would not put it, it duplicates the information already in the issue tracker

To say that it duplicates that info misleadingly implies that would be a bad thing. It presents a different view of the same information, which is useful in different circumstances.

Different view, same content,

It's not the same content. That's the key point. For example, look at this sentence in the existing Known Issues wiki page:

This was done for consistency with the rest of Magit and because
it is no longer possible to turn on --amend while editing the
message."

This is not duplicated anywhere else. Where is it going to come from in the scheme you are proposing?

has to be synchronized with any changes to the issue anyways, hence: duplication, more effort.

Yes, of course there is some duplication - it's a summary, so by definition there is duplication. And of course it takes more effort, and we don't want to place that extra burden solely on the maintainer. This is why it's important to encourage anyone who changes code to also change any corresponding documentation, including a summary of known issues. But if the docs live in a separate place to the code, it's easy for lazy or forgetful contributors to miss this step.

"Superfluous" is defined as "being more than is sufficient or required; excessive". What's your logic for describing it this way? Are commits to tests and documentation superfluous? No. And this is just another type of documentation.

This is a release artifact, not a source artifact. Does it history add anything to the understanding of the source? No, hence, superfluous.

I'm mystified how you can claim that it adds nothing to the understanding of the source. That's the whole point of the document!

Again, you seem to be assuming that a simple list of issue numbers / titles (and maybe descriptions, or extracts thereof) is sufficient. It is not.

Well, but it doesn't need to be a work at Shakespeare level, does it? It needs to be non-ambiguous, up-to-date, easy to read and understand.

We're agreed on this, at least. But a decent summary of known issues is not just a grouped list of hyperlinks to issues in the tracker. It also needs explanations written by a human being. That is what we already have in the wiki, so I'm not sure why you seem to be proposing dropping those sentences.

If you can actually demonstrate a working prototype which automatically generates a useful known issues page which has decent summaries and explanations, please do, because then I'd be willing to change my mind. I'd also happily congratulate you for significantly advancing the boundaries of Artificial Intelligence :-)

Having said all that, this debate is becoming rather pointless because I seem to be repeating things to no great effect, and anyway the maintainer ultimately has to decide how to handle this, not us. Therefore this will be my last post on this issue.

[mgalgs]

+1 all of the OP's points.

it would not have happened had I followed my instinct instead of folding due to overwhelming opposition. Doing that would have saved users from having to get involved to be able to use fundamental magit features again.

I can vouch for @tarsius that he was trying to maintain backwards compatibility. He was pushed into dropping mle by just a few vocal participants. I think the real problem is that the decision to drop mle was made in relative obscurity. I, for one, plan to rectify that personally by adding the various magit repos to my "Watch" list and look forward to the new mailing list on Savannah (I also can't stand the Google Groups interface, @tarsius). I hope more people do the same to avoid this type of debacle in the future.

I think a plain-text NEWS file at the root of the repo would be superior to a wiki/twitter/web page/microblog/macroblog/mediumblog/facebook/g+ community/subreddit/however else people communicate on the Internet. Simple, self-contained, discoverable, doesn't require a web browser.

Looks like it's been a crazy couple of months. Hang in there, man! :)

[aspiers]

There's going to be a proper mailing list? Great! I can't stand Google's rich-text-obsessed Groups interface either :)

[tarsius]

I am closing this now. We will provide more documentation of various forms, when we make the release, and we will take points that were raised here into account.