|
1 | 1 | # How to Contribute |
2 | | - |
3 | | -This project is still a work in progress, but we encourage everyone to join, propose ideas and help in the development! |
| 2 | +> Welcome to the ml5 project! Developing ml5 is not just about developing machine learning software, it is about making machine learning approachable for a broad audience of artists, creative coders, and students. The library provides access to machine learning algorithms and models in the browser, building on top of TensorFlow.js with no other external dependencies. The library is supported by code examples, tutorials, and sample datasets with an emphasis on ethical computing. Bias in data, stereotypical harms, and responsible crowdsourcing are part of the documentation around data collection and usage. We're building **friendly** machine learning for the web - we're glad you're here! |
| 3 | +
|
| 4 | + |
| 5 | + |
| 6 | +## The ml5 ecosystem (last updated: 22, March 2019) |
| 7 | + |
| 8 | +ml5.js is comprised a number of sister repositories which you can find at the [ml5 github organization - github.com/ml5js](https://github.com/ml5js). As a contributor of ml5 you should be aware of the other parallel repositories of the ml5 project. |
| 9 | + |
| 10 | +- **The 3 main repositories you'll likely be working with**: |
| 11 | + + [ml5-library]([https://github.com/ml5js](https://github.com/ml5js/ml5-library)) |
| 12 | + * this is the main ml5js library. When building the library, all of the files in the `/src` directory get bundled into the `ml5.js` library. Releases to the ml5 library get sent to `npm` and are hosted at https://unpkg.com/ (e.g. `https://unpkg.com/[email protected]/dist/ml5.min.js`) |
| 13 | + + [ml5-examples](https://github.com/ml5js/ml5-examples) |
| 14 | + * the ml5-examples repo showcases the functionality of the ml5-library. When submitting new features or updates to the ml5 library, you should also make a pull request to the ml5-examples repo to showcase how your new feature works. Usually examples are submitted in a simple p5.js sketch, but they can also be in vanilla javascript. |
| 15 | + + [ml5-website](https://github.com/ml5js/ml5-website) |
| 16 | + * the ml5-website is what you see here: https://ml5js.org/. As we make changes to the ml5 API and examples, the website also needs to be updated. For now, we're working with a manual process to updating changes, but we're working on development processes to help sync all these efforts. For now, make sure to update the ml5-examples and ml5-website when making changes to ml5-library and vice-versa. |
| 17 | +- **Data and models**: |
| 18 | + + [ml5-data-and-models](https://github.com/ml5js/ml5-data-and-models) |
| 19 | + * This repository stores data sets and pre-trained models you can use in ml5.js. |
| 20 | + + [pix2pix_models](https://github.com/ml5js/pix2pix_models): |
| 21 | + * A collection of pix2pix models |
| 22 | ++ **Training your own models**: |
| 23 | + + [training-lstm](https://github.com/ml5js/training-lstm) |
| 24 | + * Multi-layer Recurrent Neural Networks (LSTM, RNN) for character-level language models in Python using Tensorflow and modified to work with tensorflow.js and ml5js |
| 25 | + + [training-word2vec](https://github.com/ml5js/training-word2vec) |
| 26 | + * How to train your own word2vec model for use with ml5.js |
| 27 | + + [training-styletransfer](https://github.com/ml5js/training-styletransfer) |
| 28 | + * This repository contains a slightly modified version of Fast Style Transfer in TensorFlow. It trains a neural network on the style of any image you provide it and outputs a model you can use in ml5.js with the ml5.styleTransfer() method. |
| 29 | + + [training-pix2pix](https://github.com/ml5js/training-pix2pix) |
| 30 | + * documentation coming soon |
| 31 | + |
| 32 | +## Contributing Workflow |
| 33 | + |
| 34 | +Preamble: If you're interested in to contribute to the ml5 project, just know you can always open an issue to ask questions or flag things that may seem confusing, unclear or intimidating. Our goal is to make ml5 as open and supportive as possible for those who want to be involved. Ok, now that's out of the way, here's how a general workflow for what contributions might look like to ml5. |
| 35 | + |
| 36 | +### For bug fixes |
| 37 | +1. you read the CONTRIBUTING.md docs ❤️ |
| 38 | +2. you take a peek at the [issues](https://github.com/ml5js/ml5-library/issues) and identify one you'd like to address OR you file an issue about a bug you discovered. 🐛 |
| 39 | +3. you make a comment on an existing issue or post your issue and indicate that you're curious to do your best to solve it 🔬 |
| 40 | +4. you create a new branch on your `forked` copy of the ml5-library and call it something meaningful like `fix-detection-results` |
| 41 | +5. you jam on fixing the bug, commit your changes with meaningful commit messages, and push your changes to your bug fix branch (e.g. `fix-detection-results`) |
| 42 | +6. when ready, make a pull request to the `release` branch or `development` branch of ml5-library. Submit to the `release` branch if the bug you found was in the current ml5 release - the version of ml5 which is on npm. Submit to the `development` branch if the bug you found was in `developmpent` branch of ml5-library. |
| 43 | +7. the ml5 dev team will review your changes and quite likely correspond with you on your changes. When all looks good, your changes will be merged in. 🎉 |
| 44 | +8. hi-fives 👏 and hugs 🤗 |
| 45 | + |
| 46 | +### For new features or feature additions/updates |
| 47 | +1. you read the CONTRIBUTING.md docs ❤️ |
| 48 | +2. you take a peek at the [issues](https://github.com/ml5js/ml5-library/issues) and identify one you'd like to address OR you file an issue about the feature you're looking to add or update. 🐛 |
| 49 | +3. you make a comment on an existing issue or post your issue and indicate that you're curious to do your best to add this to ml5-library 🔬 |
| 50 | +4. you create a new branch on your `forked` copy of the ml5-library and call it something meaningful like `new-generative-model-x` |
| 51 | +5. you jam on your new feature, commit your changes with meaningful commit messages, and push your changes to your new feature branch (e.g. `new-generative-model-x`) |
| 52 | +6. when ready, make a pull request to the `development` branch of ml5-library. Submit to the `development` since your feature is part of the new frontier of the ml5-library. Important is step 7 below. |
| 53 | +7. you should also submit a pull request to ml5-examples with an example of your new feature so the ml5 dev team can run your proposed feature and provide feedback. |
| 54 | +8. the ml5 dev team will review your changes and quite likely correspond with you on your changes. When all looks good, your changes will be merged in. 🎉 |
| 55 | +9. hi-fives 👏 and hugs 🤗 |
| 56 | + |
| 57 | +**Now that you have a general impression for what this process might look like, you can get started!** |
4 | 58 |
|
5 | 59 | ## Getting Started |
6 | 60 |
|
7 | 61 | If you want to help develop this library, here are the steps to get started: |
8 | 62 |
|
| 63 | + |
| 64 | +### Setup |
| 65 | + |
| 66 | +We use node.js as our development environment for bundling code, running tests, and more. If you've never used node.js before, here's the steps to get node up and running on your machine. Installation requirements differ according to your computer's operating system. Please refer to the correct setup section for your specific environment |
| 67 | + |
| 68 | +- [windows]() |
| 69 | +- [macOS]() |
| 70 | + |
| 71 | +#### For Windows Users |
| 72 | +* Install node.js Version 10: https://nodejs.org/en/download/ |
| 73 | + |
| 74 | +#### For macOS Users |
| 75 | + |
| 76 | +For mac users, we recommend installing nodejs through homebrew which is a package manager. Even further, we recommend installing nodejs using nvm which is a node version manager so that you can install different versions of nodejs and switch between them. You can skip all that and use install nodejs - https://nodejs.org/en/download/ - but we do recommend using homebrew, etc. |
| 77 | + |
| 78 | +This is how you can do this: |
| 79 | + |
| 80 | +**Install [homebrew](https://brew.sh/)** |
| 81 | + |
| 82 | +Open up your terminal and paste + enter: |
| 83 | +```sh |
| 84 | +/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" |
| 85 | +``` |
| 86 | + |
| 87 | +Next use homebrew to **install nvm and node** using the `brew` command (ref: https://www.wdiaz.org/how-to-install-nvm-with-homebrew/): |
| 88 | + |
| 89 | +```sh |
| 90 | +brew install nvm |
| 91 | +mkdir ~/.nvm |
| 92 | +nvm install node |
| 93 | +nvm install 10.15 |
| 94 | +nvm use 10 |
| 95 | + |
| 96 | +nvm run node --version |
| 97 | +``` |
| 98 | + |
| 99 | +NOTE: you may need to add the reference to nvm and node into your `bash_profile` in which case you can paste the following into the `~/.bash_profile` or `~/.zshenv` file if you are using ZSH, or in `~/.bashrc` for BASH or `~/.zshrc` for ZSH ref: https://www.wdiaz.org/how-to-install-nvm-with-homebrew/): |
| 100 | + |
| 101 | +```sh |
| 102 | +export NVM_DIR="$HOME/.nvm" |
| 103 | +NVM_HOMEBREW="/usr/local/opt/nvm/nvm.sh" |
| 104 | +[ -s "$NVM_HOMEBREW" ] && \. "$NVM_HOMEBREW" |
| 105 | +``` |
| 106 | + |
| 107 | +### Developing ml5 |
| 108 | + |
9 | 109 | 1. Fork the repository to your account, and then clone it your computer: |
10 | | - ```bash |
11 | | - git clone https://github.com/YOURGITHUBHANDLE/ml5-library.git |
12 | | - ``` |
| 110 | + ```bash |
| 111 | + git clone https://github.com/YOURGITHUBHANDLE/ml5-library.git |
| 112 | + ``` |
13 | 113 |
|
14 | 114 | 2. Install dependencies: |
15 | 115 |
|
16 | | - ```bash |
17 | | - cd ml5-library |
18 | | - npm install |
19 | | - ``` |
| 116 | + ```bash |
| 117 | + cd ml5-library |
| 118 | + npm install |
| 119 | + ``` |
20 | 120 |
|
21 | 121 | 3. This project is developed using [Webpack](https://webpack.js.org/). Webpack is a module bundler that "bundles" different files into one file. This file is usually called a library. |
22 | 122 |
|
@@ -57,12 +157,20 @@ If you want to help develop this library, here are the steps to get started: |
57 | 157 | + 501 hidden modules |
58 | 158 | webpack: Compiled successfully. |
59 | 159 | ``` |
60 | | - |
| 160 | +  |
| 161 | +  |
| 162 | + |
61 | 163 | If you see this message, it means the project is actively being built by Webpack's `webpack-dev-server`. Any changes you make to any file in the `/src` folder will automatically rebuild the `ml5.js` and `ml5.min.js` libraries as long as the server continues to run. |
62 | 164 |
|
63 | 165 | 4. Develop! |
64 | 166 |
|
65 | | - Create a new folder called `/experiments` in the project's root folder. Create an `index.html` file inside `/experiments` and add the following: |
| 167 | + Run this command from the root of the project: |
| 168 | +
|
| 169 | + ```bash |
| 170 | + npm run manual-test |
| 171 | + ``` |
| 172 | +
|
| 173 | + This creates a new folder called `/manual-test` in the project's root folder. Create an `index.html` file inside `/manual-test` and add the following: |
66 | 174 |
|
67 | 175 | ```html |
68 | 176 | <!DOCTYPE html> |
@@ -127,7 +235,7 @@ If you want to help develop this library, here are the steps to get started: |
127 | 235 |
|
128 | 236 | Just be sure to add files before running commitizen! |
129 | 237 |
|
130 | | -7. (OPTIONAL) Push your code and submit a Pull Request! |
| 238 | +7. (OPTIONAL) Push your code and submit a Pull Request! Remember if you make a pull request on a new features or feature update you should make a parallel pull request to the ml5-examples repo so that others can use your new feature and test it out. |
131 | 239 |
|
132 | 240 | ## Running Unit Tests |
133 | 241 |
|
|
0 commit comments