Skip to content

Commit

Permalink
doc: add developer guide and readme
Browse files Browse the repository at this point in the history
Signed-off-by: Yulong Ruan <ruanyl@amazon.com>
  • Loading branch information
ruanyl committed Jan 30, 2023
1 parent e3f6c52 commit cd7dfb1
Show file tree
Hide file tree
Showing 3 changed files with 138 additions and 5 deletions.
58 changes: 58 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,64 @@ To send us a pull request, please:
GitHub provides additional document on [forking a repository](https://help.github.com/articles/fork-a-repo/) and
[creating a pull request](https://help.github.com/articles/creating-a-pull-request/).

## Developer Certificate of Origin

OpenSearch is an open source product released under the Apache 2.0 license (see either [the Apache site](https://www.apache.org/licenses/LICENSE-2.0) or the [LICENSE.txt file](LICENSE.txt)). The Apache 2.0 license allows you to freely use, modify, distribute, and sell your own products that include Apache 2.0 licensed software.

We respect intellectual property rights of others and we want to make sure all incoming contributions are correctly attributed and licensed. A Developer Certificate of Origin (DCO) is a lightweight mechanism to do that.

The DCO is a declaration attached to every contribution made by every developer. In the commit message of the contribution, the developer simply adds a `Signed-off-by` statement and thereby agrees to the DCO, which you can find below or at [DeveloperCertificate.org](http://developercertificate.org/).

```
Developer's Certificate of Origin 1.1
By making a contribution to this project, I certify that:
(a) The contribution was created in whole or in part by me and I
have the right to submit it under the open source license
indicated in the file; or
(b) The contribution is based upon previous work that, to the
best of my knowledge, is covered under an appropriate open
source license and I have the right under that license to
submit that work with modifications, whether created in whole
or in part by me, under the same open source license (unless
I am permitted to submit under a different license), as
Indicated in the file; or
(c) The contribution was provided directly to me by some other
person who certified (a), (b) or (c) and I have not modified
it.
(d) I understand and agree that this project and the contribution
are public and that a record of the contribution (including
all personal information I submit with it, including my
sign-off) is maintained indefinitely and may be redistributed
consistent with this project or the open source license(s)
involved.
```

We require that every contribution to OpenSearch is signed with a Developer Certificate of Origin. Additionally, please use your real name. We do not accept anonymous contributors nor those utilizing pseudonyms.

Each commit must include a DCO which looks like this

```
Signed-off-by: Jane Smith <jane.smith@email.com>
```

You may type this line on your own when writing your commit messages. However, if your user.name and user.email are set in your git configs, you can use `-s` or `--signoff` to add the `Signed-off-by` line to the end of the commit message.

## License Headers
New files in your code contributions should contain the following license header. If you are modifying existing files with license headers, or including new files that already have license headers, do not remove or modify them without guidance.

### Typescript/Javascript
```
/*
* Copyright OpenSearch Contributors
* SPDX-License-Identifier: Apache-2.0
*/
```


## Finding contributions to work on
Looking at the existing issues is a great way to find something to contribute on. As our projects, by default, use the default GitHub issue labels (enhancement/bug/duplicate/help wanted/invalid/question/wontfix), looking at any 'help wanted' issues is a great place to start.
Expand Down
71 changes: 71 additions & 0 deletions DEVELOPER_GUIDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# Developer Guide

## Prerequisites

To work on OpenSearch-Dashboards(OSD) plugins, you must have OpenSearch and OpenSearch-Dashboards running.

1. Follow this [link](https://opensearch.org/docs/latest/install-and-configure/install-opensearch/index/) to setup OpenSearch, you can easily get OpenSearch up and running [with Docker](https://opensearch.org/docs/latest/install-and-configure/install-opensearch/docker/)
2. You also need to run OSD dev server, check this [link](https://github.com/opensearch-project/OpenSearch-Dashboards/blob/main/DEVELOPER_GUIDE.md) to setup local development environment

## Setup

1. Fork this repository
2. Change working directory to OSD `/plugins` folder: `cd OpenSearch-Dashboards/plugins`
3. Clone this repo to plugins folder, `git clone git@github.com:<your-github-username>/ml-commons-dashboards.git ./`

## Install and Run

```bash
# install dependencies in OpenSearch-Dashboards/plugins/ml-commons-dashboards
cd ml-commons-dashboards
yarn osd bootstrap

# Go to OSD project root and run bootstrap to make sure all deps are installed
yarn osd bootstrap

# start OSD dev server
yarn start
```

If everything went well, OSD will be available on `http://localhost:5601/`

## Unit Test

In `plugins/ml-commons-dashboards` folder

```bash
# run tests
yarn test:jest

# or in watch mode
yarn test:jest --watch
```

NOTE: Before creating a pull request, please make sure all tests are passed. You’re also encouraged to write tests to cover the code changes you made.

## Release

### Tagging & Versioning

## Project Conventions

When contributing the codes, please read [OpenSearch-Dashboards general conventions](https://github.com/opensearch-project/OpenSearch-Dashboards/blob/main/DEVELOPER_GUIDE.md#general)
and the following project conventions.

### Conventional Commit

We are following [conventional commit](https://www.conventionalcommits.org/en/v1.0.0/#specification), these commit type are used by this project:

1. `feat:` Adding a new feature
2. `fix:` Fixing a bug
3. `test:` Adding new tests or correct existing tests
4. `refactor:` A code refactor which only contains non-functional changes
5. `docs:` Adding documentation
6. `build:` Changes that will affect the build system, such as webpack configuration, build scripts
7. `ci:` Changes to the CI configurations, such as GitHub Actions config change
8. `chore:` Changes that will not affect the meaning of the code, such as code formatting, code prettier, removing trailing white-space

### Merge a Pull Request

It it recommended to use "Squash and merge" strategy to merge a PR. If the PR contains commits which are logically isolated, you are encouraged to
squash the commits into several different ones and use "Rebase and merge" strategy in this case.
14 changes: 9 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,15 @@
## My Project
[![Test](https://github.com/opensearch-project/ml-commons-dashboards/actions/workflows/unit-tests-workflow.yml/badge.svg?branch=main)](https://github.com/opensearch-project/ml-commons-dashboards/actions/workflows/unit-tests-workflow.yml)
<br/>
<img src="https://opensearch.org/assets/brand/SVG/Logo/opensearch_logo_default.svg" height="64px"/>

TODO: Fill this README out!
## OpenSearch Machine Learning Dashboards

Be sure to:
Machine Learning Dashboards is an OpenSearch-Dashboards plugin which enables machine learning model builders to seamlessly integrate and manage the trained models on OpenSearch Dashboard.

* Change the title in this README
* Edit your repository description on GitHub
## Project Resources
1. Project Website
2. [Developer guide](DEVELOPER_GUIDE.md)
3. [Contributing to this project](CONTRIBUTING.md)

## Security

Expand Down

0 comments on commit cd7dfb1

Please sign in to comment.