I wrote up how we're putting documentation files in git in Manual:Coding_conventions [1]. It's nothing new, it mentions README.md, .txt files, etc.
I would prefer extensions on files like COPYING and HISTORY, as it's friendlier for Windows users and if the file actually uses Markdown or wikitext markup it lets Diffusion, GitHub, and syntax highlighters do a better job. I filed T116690 "Give text files in Git correct extensions".
I noticed two conventions for the extension of wikitext files in git: .mediawiki and .wiki, e.g. tests/browser/README.mediawiki and extensions/Wikibase/docs/lua.wiki. GitHub will render both kinds as MediaWiki wikitext (of course it only implements a subset); it seems Phabricator doesn't recognize either extension. I think we should be consistent. .mediawiki is more precise (it's not MoinMoin or IkeWiki markup) while .wiki is shorter. Maybe there are other arguments for one extension over the other.
Thanks for any thoughts!
[1] https://www.mediawiki.org/wiki/Manual:Coding_conventions#Text_documents
On 2015-11-03, S Page spage@wikimedia.org wrote:
I noticed two conventions for the extension of wikitext files in git: .mediawiki and .wiki, e.g. tests/browser/README.mediawiki and extensions/Wikibase/docs/lua.wiki. GitHub will render both kinds as MediaWiki wikitext (of course it only implements a subset); it seems Phabricator doesn't recognize either extension. I think we should be consistent. .mediawiki is more precise (it's not MoinMoin or IkeWiki markup) while .wiki is shorter. Maybe there are other arguments for one extension over the other.
If both "README" and "README.mediawiki" were present I'd tend to think that this is some imported piece of software and README is the upstream README file and README.mediawiki contains MW-specific bits (like import/upstreaming instructions, whatever). Something we might start to see in vendor/ eventually.
I avoid extensions for text files without source code at all, but maybe because I don't use Windows a lot.
Somehow funny we cannot use our own markup where we need to :)
Saper
The Android team uses README.mediawiki but it's just a link[0] to a wiki. It seemed appropriate to use a wiki for an app called "Wikipedia".
[0] https://www.mediawiki.org/wiki/Wikimedia_Apps/Team/Wikipedia_Android_app_hac...
On Wed, Nov 4, 2015 at 7:37 AM, Marcin Cieslak saper@saper.info wrote:
On 2015-11-03, S Page spage@wikimedia.org wrote:
I noticed two conventions for the extension of wikitext files in git: .mediawiki and .wiki, e.g. tests/browser/README.mediawiki and extensions/Wikibase/docs/lua.wiki. GitHub will render both kinds as MediaWiki wikitext (of course it only implements a subset); it seems Phabricator doesn't recognize either extension. I think we should be consistent. .mediawiki is more precise (it's not MoinMoin or IkeWiki markup) while .wiki is shorter. Maybe there are other arguments for one extension over the other.
If both "README" and "README.mediawiki" were present I'd tend to think that this is some imported piece of software and README is the upstream README file and README.mediawiki contains MW-specific bits (like import/upstreaming instructions, whatever). Something we might start to see in vendor/ eventually.
I avoid extensions for text files without source code at all, but maybe because I don't use Windows a lot.
Somehow funny we cannot use our own markup where we need to :)
Saper
Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Stephen Niedzielski sniedzielski@wikimedia.org wrote:
The Android team uses README.mediawiki but it's just a link[0] to a wiki. It seemed appropriate to use a wiki for an app called "Wikipedia".
[0] https://www.mediawiki.org/wiki/Wikimedia_Apps/Team/Wikipedia_Android_app_hac...
[...]
That destroys the self-containedness of source code. README, INSTALL & Co. should have information and instruc- tions referring to the specific version of a software, ei- ther in a distribution tarball or in a particular branch, and they should be updated in sync with changes to the source that affect them so that a user can successfully use it.
There may be additional information elsewhere, like coding conventions patches by the user must meet to be accepted or general design considerations, but a user should not have to guess how to get a software running.
Tim
No bikeshedding? Then .wiki , brevity wins. [1], thanks.
On Wed, Nov 4, 2015 at 6:37 AM, Marcin Cieslak saper@saper.info wrote:
If both "README" and "README.mediawiki" were present
It feels odd to have both. We have this in core for historical reasons, Krenair added: Symlink README.mediawiki to README so Github renders it as wikitext.
... I'd tend to think that this is some imported piece of software and README is the upstream README file and README.mediawiki contains MW-specific bits (like import/upstreaming instructions, whatever). Something we might start to see in vendor/ eventually.
Good point, though e.g. README_MediaWiki.wiki would be less confusing if they have different content.
Somehow funny we cannot use our own markup where we need to :)
We can: again, GitHub will render some MediaWiki syntax in files with the extension.wiki [2]. Phabricator's diffusion renders them as text, which is no worse than a file without extension. Also, there's a chance [3] we'll gain the ability to transclude doc files in git into wiki pages for some DRY [4] win, e.g. with the Android README that Stephen Niedzielski mentioned.
[1] https://www.mediawiki.org/w/index.php?title=Manual%3ACoding_conventions&... [2] https://help.github.com/articles/supported-mediawiki-formats/ [3] https://phabricator.wikimedia.org/T91626 [4] https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
wikitech-l@lists.wikimedia.org