From f814d33de77d649ce0b28ecb811874492b9841ca Mon Sep 17 00:00:00 2001 From: Kaartic Sivaraam Date: Wed, 18 Apr 2018 17:12:31 +0530 Subject: [PATCH] Add CONTRIBUTING file (#879) * docs: add an initial version of commit message/contributors guideline The project has long evolved without a guideline for commit messages and a contributors guideline. This has led to a lot mysteries in the code base. To avoid such mysteries in the code base in the future, add an intial version of the commit message guideline in the form of a contributors guideline. The name 'CONTRIBUTING' is pretty common and also ensures that GitHub (the place where this project currnetly evolves) brings the document to notice to an user trying to create Pull Request. Further, the all caps ensure it catches the eyes of the gazing user. This initial version of guideline is based on the git project's guideline for submitting patches (Documentation/SubmittingPatches). * contributing: remove internal link Markdown doesn't seem to be supporting internal links(fragments) to other parts of the document. So, replace it with normal text to refer to the section. * contributing: fix typo and improve sentence * contributing: add link to related wiki page * contributing: fix typo * contributing: quote section name correectly Only part of the name of a section was quoted thus referring to an inexistent section and making the sentence meaningless. So, quote it completely. * contributing: use plural to refer to wiki pages A change might obsolete "multiple" Wiki pages, which have technical documentation about the app. So, use plural to refer to the wiki pages. * contributing: move the main contributing file to the wiki The document was based on Git project's guidelines for submitting patches (Documentation/SubmittingPatches). As it was licensed under GPLv2 while this porject is licensed under an Apache license a license conflict arose. To solve it move the main document which might be susceptible to license issues to the wiki while keeping a jist of it in the document itself. * contributing: use lenient wording for steps that might be optional It's not possible to write tests for all changes. For example, UI changes. Also, it's not the case that the Wiki pages become stale all the time. So, use lineant wordings for optional steps * contributing: correct grammar in a sentence "documented in" reads better than "documented at" (at least for me). If this is wrong then we can revert it. * contributing: add link to guidelines in the wiki page * contributing: replace 'jist' with 'gist' "Jist is a pronunciation spelling of the word just when spoken with an American Southern accent. Gist is a noun that means a quick summary or the main point of something." I intended to use the latter. So, .. --- CONTRIBUTING.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ee7f42e06..0f1feeac7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1 +1,19 @@ -Please see our guidelines in the wiki: https://github.com/commons-app/apps-android-commons/wiki/Volunteers-welcome%21 +Thanks for considering to contribute to this project! A few guidelines for +people who want to contribute their code to this software are documented in +[this project's Wiki](https://github.com/commons-app/apps-android-commons/wiki/Contributing-Guidelines). +If you're not sure where to start head on to [this wiki page](https://github.com/commons-app/apps-android-commons/wiki/Volunteers-welcome!). + +Here's a gist of the guidelines, + +# Make separate commits for logically separate changes + +# Describe your changes well in the commit message + +The first line of the commit message should be a short description of what has +changed. It is also good to prefix the first line with "area: " where the "area" +is a filename or identifier for the general area of the code being modified. +The body should provide a meaningful commit message. + +# Write tests for your code (if possible) + +# Make sure the Wiki pages don't become stale by updating them (if needed)