|
| 1 | +--- |
| 2 | +description: >- |
| 3 | + Contributing guide to scikit.js including set up guide, and a brief intro to folder structure |
| 4 | +--- |
| 5 | + |
| 6 | +# Contributing Guide |
| 7 | + |
| 8 | +All contributions, bug reports, bug fixes, documentation improvements, enhancements, and ideas are welcome. |
| 9 | + |
| 10 | +For contributors familiar with open-source, below is a quick guide to setting up scikit.js locally. |
| 11 | + |
| 12 | +```text |
| 13 | +git clone https://github.com/opensource9ja/scikit.js.git |
| 14 | +cd scikit.js |
| 15 | +git checkout -b <your-branch-name> |
| 16 | +
|
| 17 | +yarn test:clean |
| 18 | +``` |
| 19 | + |
| 20 | +The following folders are available: |
| 21 | +* `estimators`: All Machine learning algorithms. |
| 22 | +* `model_selection`: Functions related to model selection. |
| 23 | +* `preprocessing`: All functions for preprocessing data before, during and after training |
| 24 | + |
| 25 | +The following files are available in the root directory: |
| 26 | +* `index`: Entry file which exports all features. |
| 27 | +* `utils`: A collection of reusable utility functions. |
| 28 | +* `types`: A file for declaring Typescript types. |
| 29 | + |
| 30 | + |
| 31 | +Some important scripts in the package.json file are: |
| 32 | +* `test`: Run all test that satisfy the given pattern. Defaults to `test/**/**/*.test.ts` (All tests will be run) |
| 33 | +* `test:clean` : Build the source to `dist` folder before running all test that satisfy the given pattern. This is useful when testing a new feature. |
| 34 | +* `build` : Compiles the src to the `dist` folder. |
| 35 | +* `build:clean` : Cleans/Remove old folders before compiling the src to the `dist` folder. |
| 36 | + |
| 37 | + |
| 38 | +## Code Style |
| 39 | +### File names |
| 40 | +File names must be all lowercase and compound names must be seperated by dots (.). E.g `label.encoder.ts`. |
| 41 | + |
| 42 | +### Source file structure |
| 43 | + |
| 44 | +Files consist of the following, in order: |
| 45 | + |
| 46 | + - License or copyright information, if present |
| 47 | + - ES import statements |
| 48 | + - The file’s source code |
| 49 | + |
| 50 | + Example: |
| 51 | + |
| 52 | + ```javascript |
| 53 | +/** |
| 54 | +* @license |
| 55 | +* Copyright 2021, JsData. All rights reserved. |
| 56 | +* |
| 57 | +* This source code is licensed under the MIT license found in the |
| 58 | +* LICENSE file in the root directory of this source tree. |
| 59 | +
|
| 60 | +* Unless required by applicable law or agreed to in writing, software |
| 61 | +* distributed under the License is distributed on an "AS IS" BASIS, |
| 62 | +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 63 | +* See the License for the specific language governing permissions and |
| 64 | +* limitations under the License. |
| 65 | +* ========================================================================== |
| 66 | +*/ |
| 67 | + |
| 68 | +import table from 'table-data' |
| 69 | +import me from 'you' |
| 70 | +import { cat, dog, eagle } from '../animals' |
| 71 | + |
| 72 | +/** |
| 73 | + * Returns the sum of two numbers |
| 74 | + * @param number num1 |
| 75 | + * @param number num2 |
| 76 | + * @returns number |
| 77 | + */ |
| 78 | + getSum(num1, num2) { |
| 79 | + return num1 + num2 |
| 80 | + |
| 81 | + ``` |
| 82 | +
|
| 83 | +### Naming Convention |
| 84 | +
|
| 85 | +#### Class names |
| 86 | +Class, interface, record, and typedef names are written in UpperCamelCase e.g `ImageProcessor`. |
| 87 | +Type names are typically nouns or noun phrases. For example, Request, ImmutableList, or VisibilityMode. |
| 88 | +
|
| 89 | +#### Method names |
| 90 | +Method names are written in lowerCamelCase e.g `addNum`. Names for private methods must start with a dollar sign e.g `$startAddition`, and should be declared as private. |
| 91 | +
|
| 92 | +Method names are typically verbs or verb phrases. For example, `sendMessage` or `$stopProcess`. Getter and setter methods for properties are never required, but if they are used they should be named `getFoo` (or optionally `isFoo` or `hasFoo` for booleans), or `setFoo(value)` for setters. |
| 93 | +
|
| 94 | +#### Constant names |
| 95 | +Constant names use `CONSTANT_CASE`: all uppercase letters, with words separated by underscores. |
| 96 | +
|
| 97 | +### JSDOC Guidelines |
| 98 | +
|
| 99 | +Documentation helps clarify what a function or a method is doing. It also gives insight to users of the function or methods on what parameters to pass in and know what the function will return. |
| 100 | +
|
| 101 | +Sample documentation: |
| 102 | +
|
| 103 | +```javascript |
| 104 | + /** |
| 105 | + * Add two series of the same length |
| 106 | + * @param series1 The first Series. Defaults to [] |
| 107 | + * @param series2 The second Series. Defaults to [] |
| 108 | + * @returns Series |
| 109 | + * @example |
| 110 | + * ``` |
| 111 | + * import { addSeries } from "scikit.js" |
| 112 | + * |
| 113 | + * const newSeries = addSeries(Sf1, Sf2) |
| 114 | + * newSeries.shape.print() |
| 115 | + * // [10, 4] |
| 116 | + * ``` |
| 117 | + */ |
| 118 | +const addSeries = (series1, series2) => { |
| 119 | + //DO something here |
| 120 | + return new Series() |
| 121 | +} |
| 122 | + |
| 123 | +``` |
| 124 | +
|
| 125 | +## **Writing tests** |
| 126 | +
|
| 127 | +We strongly encourage contributors to write tests for their code. Like many packages, danfojs uses mocha |
| 128 | +
|
| 129 | +All tests should go into the tests subdirectory and place in the corresponding module. The tests folder contains some current examples of tests, and we suggest looking to these for inspiration. |
| 130 | +
|
| 131 | +Below is the general Framework to write a test for each module. |
| 132 | +
|
| 133 | +```javascript |
| 134 | +import { assert } from "chai" |
| 135 | +import { addSeries } from '../../dist' //compiled build |
| 136 | + |
| 137 | +describe("Name of the class|module", function(){ |
| 138 | + |
| 139 | + it("name of the methods| expected result",function(){ |
| 140 | + |
| 141 | + //write your test code here |
| 142 | + //use assert.{proprty} to test your code |
| 143 | + }) |
| 144 | + |
| 145 | +}); |
| 146 | +``` |
| 147 | +
|
| 148 | +For a class with lots of methods. |
| 149 | +
|
| 150 | +```python |
| 151 | +import { assert } from "chai" |
| 152 | +import { DataFrame } from '../../src/core/frame' |
| 153 | + |
| 154 | +describe("Name of the class|module", function(){ |
| 155 | + |
| 156 | + describe("method name 1", function(){ |
| 157 | + |
| 158 | + it("expected result",function(){ |
| 159 | + |
| 160 | + //write your test code here |
| 161 | + //use assert.{proprty} to test your code |
| 162 | + }) |
| 163 | + }) |
| 164 | + |
| 165 | + describe("method name 2", function(){ |
| 166 | + |
| 167 | + it("expected result",function(){ |
| 168 | + |
| 169 | + //write your test code here |
| 170 | + //use assert.{proprty} to test your code |
| 171 | + }) |
| 172 | + }) |
| 173 | + ....... |
| 174 | +}); |
| 175 | +``` |
| 176 | +
|
| 177 | +
|
| 178 | +
|
| 179 | +### **Running the test case** |
| 180 | +
|
| 181 | +To run the test for the module/file you created/edited, |
| 182 | +
|
| 183 | +**1\)** Open the package.json |
| 184 | +
|
| 185 | +**2\)** change the name of the test file to the file name you want. and don't forget the file is in the test folder |
| 186 | +
|
| 187 | +```python |
| 188 | +"scripts": { |
| 189 | + "test": "....... tests/[sub_directory_name]/filename.test.ts", |
| 190 | +``` |
| 191 | +
|
| 192 | +**3\)** run the test in clean mode |
| 193 | +
|
| 194 | +```python |
| 195 | +yarn test:clean |
| 196 | +``` |
| 197 | +
|
| 198 | +Learn more about mocha [here](https://mochajs.org/) |
0 commit comments