|
| 1 | +# Contributing |
| 2 | + |
| 3 | +If you would like to contribute new example apps to the `elasticsearch-labs` repo, we would love to hear from you! |
| 4 | + |
| 5 | +## Before you start |
| 6 | + |
| 7 | +Prior to opening a pull request, please: |
| 8 | +- Create an issue to [discuss the scope of your proposal](https://github.com/elastic/elasticsearch-labs/issues). We are happy to provide guidance to make for a pleasant contribution experience. |
| 9 | +- Sign the [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. |
| 10 | + |
| 11 | +## Contributing to Python notebooks 📒 |
| 12 | + |
| 13 | +### Why |
| 14 | + |
| 15 | +* The main goal of this repo is to help people learn about solving various problems with the Elastic Stack using step-by-step interactive guides and specific applications. |
| 16 | +* Remember your target audience: developers who want to try out some technology with Elastic. They may not be familiar with all the technologies. |
| 17 | + |
| 18 | +### Where |
| 19 | + |
| 20 | +* Select a folder under [notebooks](../notebooks/README.md) that matches the category of your notebook. If none of them match, create a new folder. |
| 21 | + |
| 22 | +### What |
| 23 | + |
| 24 | +* Add your `.ipynb` file to the folder. |
| 25 | +* The notebook should be self-contained. Avoid cross-linking code, data files, configuration etc. from other folders. |
| 26 | +* We prefer the `kebab-case` file naming convention. |
| 27 | +* Please write simple code and concise documentation, where appropriate. |
| 28 | +* Start with a text cell that summarizes what the notebook will demonstrate. Feel free to use images - sometimes a picture is worth a thousand words. |
| 29 | +* Add a header and description section before each code cell. Explain in simple terms what the code will be doing and what the expected outcome is. |
| 30 | +* When the output of a cell is relevant, preserve it in the notebook. |
| 31 | +* Update the `README.md` file in the folder of the notebook. |
| 32 | + |
| 33 | +### How |
| 34 | + |
| 35 | +* We recommend building the notebook in an interactive environment, such as [Google Colab](https://colab.google/). This way you can test all the steps and capture the output. |
| 36 | +* **Never leave any secrets in the code** (API keys, passwords etc). Also avoid hardcoding URLs and IDs that may change from user to user. Instead use environment variables that need to be set by the user while they are running the notebook. |
| 37 | +* Test your notebook end to end before submitting a pull request. |
| 38 | +* Example of a well-formed notebook: [question-answering.ipynb](../notebooks/generative-ai/question-answering.ipynb). |
| 39 | + |
| 40 | +## Contributing to example applications 💻 |
| 41 | + |
| 42 | +### Why |
| 43 | + |
| 44 | +* The main goal of this repo is to help people learn about solving various problems with the Elastic Stack using step-by-step interactive guides and specific applications. |
| 45 | +* Remember your target audience: developers who want to try out some technology with Elastic. They may not be familiar with all the technologies. |
| 46 | + |
| 47 | +### Where |
| 48 | + |
| 49 | +* Select a folder under [example-apps](../example-apps/README.md) that matches the category of your applications. If none of them match, create a new folder. |
| 50 | +* Create a folder under the category for your applications. |
| 51 | + |
| 52 | +### What |
| 53 | + |
| 54 | +* Add your app's files to the folder. |
| 55 | +* The app should be self-contained. Avoid cross-linking code, data files, configuration etc. from other folders. |
| 56 | +* Please write simple code and concise documentation, where appropriate. |
| 57 | +* Add a `README.md` file in the root folder of the app: |
| 58 | + * Summarize what the app will demonstrate. Feel free to use images - sometimes a picture is worth a thousand words. |
| 59 | + * List language requirements in the readme file, e.g. "Python 3.6+". |
| 60 | + * List clear instructions for installing and runing the example app in the readme file. This includes |
| 61 | + * Upload sample data files as necessary, or instructions for downloading them from an external source. Consider the license for any datasets. |
| 62 | + * Mention the version of the Elastic Stack that the example was tested with. |
| 63 | + |
| 64 | +### How |
| 65 | + |
| 66 | +* **Never leave any secrets in the code** (API keys, passwords etc). Also avoid hardcoding URLs and IDs that may change from user to user. Instead use environment variables that need to be set by the user while they are running the app. |
| 67 | +* Test your app end to end before submitting a pull request. |
| 68 | +* Example of a well-formed app: [OpenAI-Py](../example-apps/OpenAI-embeddings/OpenAI-Py/README.md). |
0 commit comments