|
| 1 | +# Contributing Guide |
| 2 | + |
| 3 | +### Contributing to danfojs |
| 4 | + |
| 5 | +**Table of contents:** |
| 6 | + |
| 7 | +* **TL:DR** |
| 8 | +* Where to start? |
| 9 | +* Working with the code |
| 10 | + * Version control, Git, and GitHub |
| 11 | + * Getting started with Git |
| 12 | + * Forking |
| 13 | + * Creating a development environment |
| 14 | +* Documentation Guidelines |
| 15 | +* Writing tests |
| 16 | + * Using mocha |
| 17 | + * Running the test suite |
| 18 | +* Contributing your changes to danfojs |
| 19 | + * Committing your code |
| 20 | + * Pushing your changes |
| 21 | + * Review your code and finally, make the pull request |
| 22 | +* Danfojs internal (Brief) |
| 23 | + |
| 24 | +## TL:DR |
| 25 | + |
| 26 | +All contributions, bug reports, bug fixes, documentation improvements, enhancements, and ideas are welcome. |
| 27 | + |
| 28 | +For contributors familiar with open-source, below is a quick guide to setting up danfojs locally. |
| 29 | + |
| 30 | +``` |
| 31 | +git clone https://github.com/javascriptdata/danfojs.git |
| 32 | +cd danfojs |
| 33 | +git checkout -b <your-branch-name> |
| 34 | +``` |
| 35 | + |
| 36 | +There are three main folders in the `src` folder, **danfojs-base**, **danfojs-browser,** and **danfojs-node**.  |
| 37 | + |
| 38 | +The **danfojs-base** folder holds all shared classes, modules, and functions used by both danfojs-browser and danfojs-node. So features or bug fixes that work the same way in both versions will generally be done in the **danfojs-base** folder.  |
| 39 | + |
| 40 | +## Where to start? |
| 41 | + |
| 42 | +For first-time contributors, you can find pending issues on the GitHub “issues” page. There are a number of issues listed and "good first issue" where you could start out. Once you’ve found an interesting issue, and have an improvement in mind, next thing is to set up your development environment. |
| 43 | + |
| 44 | +## Working with the code |
| 45 | + |
| 46 | +If you have an issue you want to fix, an enhancement to add, or documentation to improve, you need to learn how to work with GitHub and the Danfojs code base. |
| 47 | + |
| 48 | +### **Version control, Git, and GitHub** |
| 49 | + |
| 50 | +Danfojs code is hosted on GitHub. To contribute you will need to sign up for a free GitHub account. We use Git for version control to allow many people to work together on this project. |
| 51 | + |
| 52 | +Some great resources for learning Git: |
| 53 | + |
| 54 | +* Official [GitHub pages](http://help.github.com). |
| 55 | + |
| 56 | +### **Getting started with Git** |
| 57 | + |
| 58 | +Find [Instructions](http://help.github.com/set-up-git-redirect) for installing git, setting up your SSH key, and configuring git. These steps need to be completed before you can work seamlessly between your local repository and GitHub. |
| 59 | + |
| 60 | +## **Forking the Danfojs repo** |
| 61 | + |
| 62 | +You will need your own fork to work on the code. Go to the danfojs [project page](https://github.com/opensource9ja/danfojs) and hit the Fork button. |
| 63 | + |
| 64 | +Next, you will clone your fork to your local machine: |
| 65 | + |
| 66 | +``` |
| 67 | +git clone https://github.com/javascriptdata/danfojs.git |
| 68 | +cd danfojs |
| 69 | +``` |
| 70 | + |
| 71 | +This creates the directory danfojs and connects your repository to the upstream (main project) repository. |
| 72 | + |
| 73 | +Some Javascript features are supported both in the browser and node environment, and it is recommended to add features in the **danfojs-base** folder.  |
| 74 | + |
| 75 | +For features that work differently or only in a specific environment, you can add them in the corresponding danfojs-node or danfojs-browser folder.  |
| 76 | + |
| 77 | + |
| 78 | + |
| 79 | +## **Creating a development environment** |
| 80 | + |
| 81 | +To test out code changes, you’ll need to build danfojs, which requires a Nodejs environment. |
| 82 | + |
| 83 | +```python |
| 84 | +git clone https://github.com/javascriptdata/danfojs.git |
| 85 | +cd danfojs |
| 86 | +yarn install ## automatically installs all required packages |
| 87 | +yarn test ##Runs test in both node and browser folder |
| 88 | +``` |
| 89 | + |
| 90 | +> Now you can start adding features or fixing bugs! |
| 91 | +
|
| 92 | +## Documentation Guidelines |
| 93 | + |
| 94 | +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. |
| 95 | + |
| 96 | +Sample documentation: |
| 97 | + |
| 98 | +```javascript |
| 99 | + /** |
| 100 | + * Add two series of the same length |
| 101 | + * @param {series1} series1 [Series] |
| 102 | + * @param {series2} series2 [Series] |
| 103 | + * @returns Series |
| 104 | + */ |
| 105 | +function add_series(series1, series2){ |
| 106 | + |
| 107 | + ................... |
| 108 | + |
| 109 | + return new Series() |
| 110 | +} |
| 111 | +``` |
| 112 | + |
| 113 | +And for functions that contain more than two arguments, a keyword argument can be used. Parsing of keyword argument is also applicable to most of the methods in a class |
| 114 | + |
| 115 | +```javascript |
| 116 | +/** |
| 117 | + * Join two or more dataframe together along an axis |
| 118 | + * @param {kwargs} kwargs --> { |
| 119 | + * df_list: [Array of DataFrame], |
| 120 | + * axis : int {0 or 1}, |
| 121 | + * by_column : String {name of a column}, |
| 122 | + * } |
| 123 | + * @returns DataFrame |
| 124 | + */ |
| 125 | +function join_df(kwargs){ |
| 126 | + ........ |
| 127 | + |
| 128 | + return DataFrame |
| 129 | +} |
| 130 | +``` |
| 131 | + |
| 132 | +## **Writing tests** |
| 133 | + |
| 134 | +We strongly encourage contributors to write tests for their code. Like many packages, Danfojs uses mocha.  |
| 135 | + |
| 136 | +All tests should go into the tests subdirectory and placed in the corresponding module. The tests folder contains some current examples of tests, and we suggest looking to these for inspiration. |
| 137 | + |
| 138 | +Below is the general Framework to write a test for each module. |
| 139 | + |
| 140 | +{% tabs %} |
| 141 | +{% tab title="JavaScript" %} |
| 142 | +```javascript |
| 143 | +import { assert } from "chai" |
| 144 | +import { DataFrame } from '../../src/core/frame' |
| 145 | + |
| 146 | +describe("Name of the class|module", function(){ |
| 147 | + |
| 148 | + it("name of the methods| expected result",function(){ |
| 149 | + |
| 150 | + //write your test code here |
| 151 | + //use assert.{proprty} to test your code |
| 152 | + }) |
| 153 | + |
| 154 | +}); |
| 155 | +``` |
| 156 | +{% endtab %} |
| 157 | +{% endtabs %} |
| 158 | + |
| 159 | +For a class with lots of methods. |
| 160 | + |
| 161 | +```python |
| 162 | +import { assert } from "chai" |
| 163 | +import { DataFrame } from '../../src/core/frame' |
| 164 | + |
| 165 | +describe("Name of the class|module", function(){ |
| 166 | + |
| 167 | + describe("method name 1", function(){ |
| 168 | + |
| 169 | + it("expected result",function(){ |
| 170 | + |
| 171 | + //write your test code here |
| 172 | + //use assert.{proprty} to test your code |
| 173 | + }) |
| 174 | + }) |
| 175 | + |
| 176 | + describe("method name 2", function(){ |
| 177 | + |
| 178 | + it("expected result",function(){ |
| 179 | + |
| 180 | + //write your test code here |
| 181 | + //use assert.{proprty} to test your code |
| 182 | + }) |
| 183 | + }) |
| 184 | + ....... |
| 185 | +}); |
| 186 | +``` |
| 187 | + |
| 188 | +**Example**: Let write a test, to test if the values in a dataframe are off a certain length. Assuming the method to obtain length is values\_len() |
| 189 | + |
| 190 | +```javascript |
| 191 | +import { assert } from "chai" |
| 192 | +import { DataFrame } from '../../src/core/frame' |
| 193 | + |
| 194 | +describe("DataFrame", function(){ |
| 195 | + |
| 196 | + describe("value_len", function(){ |
| 197 | + |
| 198 | + it("check dataframe length",function(){ |
| 199 | + |
| 200 | + let data = [[1,2],[4,5]] |
| 201 | + let columns = ["A","B"] |
| 202 | + let df = new DataFrame(data,{columns: columns}) |
| 203 | + |
| 204 | + let expected_result = 2 |
| 205 | + |
| 206 | + assert.deepEqual(sf.value_len(), expected_result)) |
| 207 | + |
| 208 | + |
| 209 | + }) |
| 210 | + }) |
| 211 | + |
| 212 | +}); |
| 213 | +``` |
| 214 | + |
| 215 | +### **Running the test case** |
| 216 | + |
| 217 | +To run the test for the module you created, |
| 218 | + |
| 219 | +**1)** Open the package.json |
| 220 | + |
| 221 | +**2)** change the name of the test script to the file name you want to test. |
| 222 | + |
| 223 | +```python |
| 224 | +"scripts": { |
| 225 | + "test": "....... danfojs/tests/sub_directory_name/filename", |
| 226 | +``` |
| 227 | + |
| 228 | +**3)** run the test, in the danfojs directory terminal |
| 229 | + |
| 230 | +```python |
| 231 | +yarn test |
| 232 | +``` |
| 233 | + |
| 234 | +Learn more about mocha [here](https://mochajs.org) |
| 235 | + |
| 236 | +## Contributing your changes to danfojs |
| 237 | + |
| 238 | +### **Committing your code** |
| 239 | + |
| 240 | +Once you’ve made changes, you can see them by typing: |
| 241 | + |
| 242 | +``` |
| 243 | +git status |
| 244 | +``` |
| 245 | + |
| 246 | +Next, you can track your changes using |
| 247 | + |
| 248 | +``` |
| 249 | +git add . |
| 250 | +``` |
| 251 | + |
| 252 | +Next, you commit changes using: |
| 253 | + |
| 254 | +``` |
| 255 | +git commit -m "Enter any commit message here" |
| 256 | +``` |
| 257 | + |
| 258 | +### **Pushing your changes** |
| 259 | + |
| 260 | +When you want your changes to appear publicly on your GitHub page, you can push to your forked repo with: |
| 261 | + |
| 262 | +``` |
| 263 | +git push |
| 264 | +``` |
| 265 | + |
| 266 | +### Review your code and finally, make a pull request |
| 267 | + |
| 268 | +If everything looks good, you are ready to make a pull request. A pull request is how code from a local repository becomes available to the GitHub community and can be reviewed and eventually merged into the master version. To submit a pull request: |
| 269 | + |
| 270 | +1. Navigate to your repository on GitHub |
| 271 | +2. Click on the Pull Request button |
| 272 | +3. Write a description of your changes in the Preview Discussion tab |
| 273 | +4. Click Send Pull Request. |
| 274 | + |
| 275 | +This request then goes to the repository maintainers, and they will review the code and everything looks good, merge it with the master. |
| 276 | + |
| 277 | +**Hooray! You're now a contributor to danfojs. Now go bask in the euphoria!** |
| 278 | + |
| 279 | +## **Danfojs Internals** |
| 280 | + |
| 281 | +In other to contribute to the code base of danfojs, there are some functions and properties provided to make implementation easy. |
| 282 | + |
| 283 | +The folder **danfojs-base** contains the bulk of Danfojs modules, and these are simply extended or exported by the **danfojs-browser** and **danfojs-node** folders. The base class for Frames and Series is the NdFrame class which is found in the `danfojs-base/core/generic` file.  |
| 284 | + |
| 285 | + |
| 286 | + |
0 commit comments