Reformat CONTRIBUTING as Markdown.
Project: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/repo Commit: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/commit/608979f9 Tree: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/tree/608979f9 Diff: http://git-wip-us.apache.org/repos/asf/lucy-clownfish/diff/608979f9 Branch: refs/heads/master Commit: 608979f9376596d8ce76bd91bb099cfca945b20a Parents: 6321270 Author: Marvin Humphrey <[email protected]> Authored: Wed Dec 30 17:09:57 2015 -0800 Committer: Marvin Humphrey <[email protected]> Committed: Wed Dec 30 17:09:57 2015 -0800 ---------------------------------------------------------------------- CONTRIBUTING.md | 116 +++++++++++++++++++++++++-------------------------- 1 file changed, 56 insertions(+), 60 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/lucy-clownfish/blob/608979f9/CONTRIBUTING.md ---------------------------------------------------------------------- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 10c92d9..52195ad 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,89 +1,85 @@ -================================ Contributing to Apache Clownfish ================================ -MAKE A PLAN: - - Clownfish is developed by the Apache Lucy community. +Make a plan +----------- - http://lucy.apache.org/ +Clownfish is developed by the [Apache Lucy](http://lucy.apache.org) community. - If you propose to make non-trivial changes to Clownfish, especially changes - to the public API, send a note to the Lucy developer's list describing your - plans: +If you propose to make non-trivial changes to Clownfish, especially changes +to the public API, send a note to the [Lucy developer's +list](http://lucy.apache.org/mailing_lists) describing your plans. - http://lucy.apache.org/mailing_lists.html - -GET THE CODE: +Get the code +------------ - Clownfish's codebase is available via Git from git-wip-us.apache.org. Start - by creating a clone of the repository: +Clownfish's codebase is available via Git from git-wip-us.apache.org. Start +by creating a clone of the repository: git clone https://git-wip-us.apache.org/repos/asf/lucy-clownfish.git - There is also a mirror on Github. +There is also a [mirror on Github](https://github.com/apache/lucy-clownfish). - https://github.com/apache/lucy-clownfish +Follow the instructions in INSTALL to set up your local workspace. - Follow the instructions in INSTALL to set up your local workspace. +Make changes +------------ -MAKE CHANGES: +Edit the source code as you see fit, then build and run tests. - Edit the source code as you see fit, then build and run tests. +Clownfish supports continuous integration services Travis and Appveyor +to run tests under multiple host languages, host language versions, and +platforms. If you fork the Github repository, you can make these services +automatically test the changes you made in your fork. - Clownfish supports continuous integration services Travis and Appveyor - to run tests under multiple host languages, host language versions, and - platforms. If you fork the Github repository, you can make these services - automatically test the changes you made in your fork. +Please bear the following in mind: - Please bear the following in mind: +* All code will eventually need to be portable to multiple operating + systems and compilers. (This is a complex requirement and it should not + block your contribution.) +* All public APIs must be documented. +* Code should be formatted according to the style guidelines at + <http://wiki.apache.org/lucy/LucyStyleGuide>. +* All unit tests must pass. +* New code needs to be accompanied by new unit tests. +* Simplicity, both in terms of API and implementation, is highly valued + within the Lucy development community; the simpler the contribution, the + more quickly it can be reviewed and integrated. - * All code will eventually need to be portable to multiple operating - systems and compilers. (This is a complex requirement and it should not - block your contribution.) - * All public APIs must be documented. - * Code should be formatted according to the style guidelines at - <http://wiki.apache.org/lucy/LucyStyleGuide>. - * All unit tests must pass. - * New code needs to be accompanied by new unit tests. - * Simplicity, both in terms of API and implementation, is highly valued - within the Lucy development community; the simpler the contribution, the - more quickly it can be reviewed and integrated. +Open an issue +------------- -OPEN AN ISSUE: +The [Clownfish issue-tracker](https://issues.apache.org/jira/browse/CLOWNFISH) +runs Atlassian JIRA and we generally use the term "issue" rather than "bug" +because not every contribution fixes a "bug": - Clownfish uses Lucy's issue-tracker/bug-tracker installation, which runs - Atlassian JIRA. We generally use the term "issue" rather than "bug" because - not every contribution fixes a "bug". - - https://issues.apache.org/jira/browse/CLOWNFISH - - 1. Create a JIRA account for yourself and sign in. - 2. Once you have signed in, the "create new issue" link will appear. Either - use it to open a new issue or navigate to an existing one as appropriate. - 3. To attach files to an issue, use the menu command - 'More Actions > Attach Files'. +1. Create a JIRA account for yourself and sign in. +2. Once you have signed in, the "create new issue" link will appear. Either + use it to open a new issue or navigate to an existing one as appropriate. +3. To attach files to an issue, use the menu command + 'More Actions > Attach Files'. - Attaching a file to an issue causes an email notification to be sent to the - lucy-issues list signalling that a patch has arrived. Please be patient but - persistent while engaging with the Lucy committers who review and apply such - patches. +Attaching a file to an issue causes an email notification to be sent to the +lucy-issues list signalling that a patch has arrived. Please be patient but +persistent while engaging with the Lucy committers who review and apply such +patches. -CONTRIBUTE A PATCH: +Contribute a patch +------------------ - The easiest way to create a patch with Git is to capture the output of - `git diff`: +The easiest way to create a patch with Git is to capture the output of +`git diff`: git diff > my_changes.patch - The resulting patch file can then be attached to a JIRA issue. - -GITHUB PULL REQUESTS +The resulting patch file can then be attached to a JIRA issue. - Github users may submit pull requests against our mirror: +Github pull requests +-------------------- - https://github.com/apache/lucy-clownfish +Github users may submit pull requests against our +[mirror](https://github.com/apache/lucy-clownfish). - An email notifying the Lucy developers list of your pull request will be - triggered automatically. +An email notifying the Lucy developers list of your pull request will be +triggered automatically.
