Add README.md

[jamesmudd]

This adds a better markdown based readme for the GitHub repository page.

[devendor]

Quick question on testing. When adding tests, where should they go?

My guess is that Lib/test/test_module.py is pretty much a copy of cpython tests for that module, while custom tests are Lib/test/test_module_jy.py are additional tests for that module related to our work.

[jeff5]

@devendor Wrong PR, but essentially yes. Other twist: unmodified tests come directly from lib-python/2.7 .

[Stewori]

@jamesmudd I would avoid to name the version number in the readme because it is too easily forgotten to update. If we really require it, I would suggest to insert it only right before an actual release and remove it right after the release. No version number in release readme is better than a wrong number. What about limiting it to 2.7?

[jamesmudd]

@Stewori I agree that we need to remember to update it. I copied the text that already exists in README.txt just formatted with markdown. I can change to 2.7 or remove it? Presumably the existing README is being updated. I don't really mind either way just thought it would make the github page look a bit better.

[Stewori]

@jamesmudd You're right that is actually a distinct discussion. I was a bit confused about the words "This is an alpha release of the 2.7.2 version of Jython." because nothing was released really. Then wondered if it's really necessary to state the version in the readme because it's easier to maintain a generic readme, like we're moving away from a news-centric website. Having version stated in so many distinct places (I think it's also in news, somewhere in the code who knows where else -- in the build file maybe?) is difficult and now it adds just another redundancy. Anyway, that's rather the release manager's business.

Do we really want README.md and README.txt in parallel? I suggest to remove README.txt in favor of README.md. As soon as we need to make edits it would be a constant annoyance to keep both in sync. Maybe it would be best to ask for permission for this change on jython-dev. Since chances are high that nobody replies to something like this I usually formulate it like "if someone sees a reason why not to make this change, please speak up." Then wait a week or so and just apply it.
If that's okay for you I'd prepare such an email.

[jamesmudd]

I agree that switching is probably easier than maintaining both, the only issue is there might still be things referencing the README.txt. I have updated the PR to do that and also to drop the versioning. I will send an email to the mailing list.

[Stewori]

Committed as of 44a3029 and 899879e. Sorry, I failed to remove README.txt in the former one and had to fix it in a second commit.

Closing.