diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..da431a6 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,162 @@ +Contributing to eland +===================== + +Eland is an open source project and we love to receive contributions +from our community --- you! There are many ways to contribute, from +writing tutorials or blog posts, improving the documentation, submitting +bug reports and feature requests or writing code which can be +incorporated into eland itself. + +Bug reports +----------- + +If you think you have found a bug in eland, first make sure that you are +testing against the [latest version of +eland](https://github.com/elastic/eland) - your issue may already have +been fixed. If not, search our [issues +list](https://github.com/elastic/eland/issues) on GitHub in case a +similar issue has already been opened. + +It is very helpful if you can prepare a reproduction of the bug. In +other words, provide a small test case which we can run to confirm your +bug. It makes it easier to find the problem and to fix it. Test cases +should be provided as python scripts, ideally with some details of your +Elasticsearch environment and index mappings, and (where appropriate) a +pandas example. + +Provide as much information as you can. You may think that the problem +lies with your query, when actually it depends on how your data is +indexed. The easier it is for us to recreate your problem, the faster it +is likely to be fixed. + +Feature requests +---------------- + +If you find yourself wishing for a feature that doesn\'t exist in eland, +you are probably not alone. There are bound to be others out there with +similar needs. Many of the features that eland has today have been added +because our users saw the need. Open an issue on our [issues +list](https://github.com/elastic/eland/issues) on GitHub which describes +the feature you would like to see, why you need it, and how it should +work. + +Contributing code and documentation changes +------------------------------------------- + +If you have a bugfix or new feature that you would like to contribute to +eland, please find or open an issue about it first. Talk about what you +would like to do. It may be that somebody is already working on it, or +that there are particular issues that you should know about before +implementing the change. + +We enjoy working with contributors to get their code accepted. There are +many approaches to fixing a problem and it is important to find the best +approach before writing too much code. + +Note that it is unlikely the project will merge refactors for the sake +of refactoring. These types of pull requests have a high cost to +maintainers in reviewing and testing with little to no tangible benefit. +This especially includes changes generated by tools. + +The process for contributing to any of the [Elastic +repositories](https://github.com/elastic/) is similar. Details for +individual projects can be found below. + +### Fork and clone the repository + +You will need to fork the main eland code or documentation repository +and clone it to your local machine. See [github help +page](https://help.github.com/articles/fork-a-repo) for help. + +Further instructions for specific projects are given below. + +### Submitting your changes + +Once your changes and tests are ready to submit for review: + +1. Test your changes + + Run the test suite to make sure that nothing is broken (TODO add + link to testing doc). + +2. Sign the Contributor License Agreement + + Please make sure you have signed our [Contributor License + Agreement](https://www.elastic.co/contributor-agreement/). We are + not asking you to assign copyright to us, but to give us the right + to distribute your code without restriction. We ask this of all + contributors in order to assure our users of the origin and + continuing existence of the code. You only need to sign the CLA + once. + +3. Rebase your changes + + Update your local repository with the most recent code from the main + eland repository, and rebase your branch on top of the latest master + branch. We prefer your initial changes to be squashed into a single + commit. Later, if we ask you to make changes, add them as separate + commits. This makes them easier to review. As a final step before + merging we will either ask you to squash all commits yourself or + we\'ll do it for you. + +4. Submit a pull request + + Push your local changes to your forked copy of the repository and + [submit a pull + request](https://help.github.com/articles/using-pull-requests). In + the pull request, choose a title which sums up the changes that you + have made, and in the body provide more details about what your + changes do. Also mention the number of the issue where discussion + has taken place, eg "Closes \#123". + +Then sit back and wait. There will probably be discussion about the pull +request and, if any changes are needed, we would love to work with you +to get your pull request merged into eland. + +Please adhere to the general guideline that you should never force push +to a publicly shared branch. Once you have opened your pull request, you +should consider your branch publicly shared. Instead of force pushing +you can just add incremental commits; this is generally easier on your +reviewers. If you need to pick up changes from master, you can merge +master into your branch. A reviewer might ask you to rebase a +long-running pull request in which case force pushing is okay for that +request. Note that squashing at the end of the review process should +also not be done, that can be done when the pull request is [integrated +via GitHub](https://github.com/blog/2141-squash-your-commits). + +Contributing to the eland codebase +---------------------------------- + +**Repository:** + +We internally develop using the PyCharm IDE. For PyCharm, we are +currently using a minimum version of PyCharm 2019.2.4. + +### Configuring PyCharm And Running Tests + +(All commands should be run from module root) + +- Create a new project via \'Check out from Version + Control\'-\>\'Git\' on the \"Welcome to PyCharm\" page (or other) +- Enter the URL to your fork of eland + (e.g. `git@github.com:stevedodson/eland.git`) +- Click \'Yes\' for \'Checkout from Version Control\' +- Configure PyCharm environment: +- In \'Preferences\' configure a \'Project: eland\'-\>\'Project + Interpreter\'. Generally, we recommend creating a virtual + environment (TODO link to installing for python version support). +- In \'Preferences\' set \'Tools\'-\>\'Python Integrated + Tools\'-\>\'Default test runner\' to `pytest` +- In \'Preferences\' set \'Tools\'-\>\'Python Integrated + Tools\'-\>\'Docstring format\' to `numpy` +- Install development requirements. Open terminal in virtual + environment and run `pip install -r requirements-dev.txt` +- Setup Elasticsearch instance (assumes `localhost:9200`), and run + `python -m eland.tests.setup_tests` to setup test environment -*note + this modifies Elasticsearch indices* +- Run `pytest --doctest-modules` to validate install + +### Documentation + +- Install documentation requirements. Open terminal in virtual + environment and run `pip install -r requirements-dev.txt` diff --git a/docs/source/development/contributing.rst b/docs/source/development/contributing.rst index 02dc723..82d9cef 100644 --- a/docs/source/development/contributing.rst +++ b/docs/source/development/contributing.rst @@ -57,8 +57,7 @@ approach before writing too much code. Note that it is unlikely the project will merge refactors for the sake of refactoring. These types of pull requests have a high cost to maintainers in reviewing and testing with little to no tangible benefit. -This especially includes changes generated by tools. For example, -converting all generic interface instances to use the diamond operator. +This especially includes changes generated by tools. The process for contributing to any of the `Elastic repositories `__ is similar. Details for