Add Developer Guide Docs to MXNet Website (#18474)

* init dev guide * move dev guide above FAQ * update format and images * hoist git docs and fix styles * use relative urls * remove useless code block * use consistent url and file name * update heading * add apache license header * init dev guide * move dev guide above FAQ * update format and images * hoist git docs and fix styles * use relative urls * remove useless code block * use consistent url and file name * update heading * add apache license header * update doc - git clone recursive * reviewing the dev guide - proof reading and text edits Co-authored-by: Yang Shi <yangshia@amazon.com> Co-authored-by: Talia Chopra <chopt@amazon.com>
apache · Jun 4, 2020 · 7cc6700 · 7cc6700
1 parent 8d220a2
commit 7cc6700
Show file tree

Hide file tree

Showing 14 changed files with 826 additions and 2 deletions.
diff --git a/docs/static_site/src/_sass/minima/_docs.scss b/docs/static_site/src/_sass/minima/_docs.scss
@@ -67,7 +67,9 @@
 }
 
 .docs-faq {
-  background-color: white;
+  background-color: $grey-color-light;
+  padding-top: 20px;
+  padding-bottom: 20px;
 }
 
 .docs-architecture {
@@ -76,4 +78,10 @@
   margin-bottom: 20px;
   padding-top: 20px;
   padding-bottom: 20px;
-}
+}
+
+.docs-dev-guide {
+  background-color: white;
+  padding-top: 20px;
+  padding-bottom: 20px;
+}
diff --git a/docs/static_site/src/assets/img/dev_guide_profilling_1.png b/docs/static_site/src/assets/img/dev_guide_profilling_1.png
diff --git a/docs/static_site/src/assets/img/dev_guide_profilling_2.png b/docs/static_site/src/assets/img/dev_guide_profilling_2.png
diff --git a/docs/static_site/src/assets/img/dev_guide_profilling_3.png b/docs/static_site/src/assets/img/dev_guide_profilling_3.png
diff --git a/docs/static_site/src/assets/img/dev_guide_profilling_4.png b/docs/static_site/src/assets/img/dev_guide_profilling_4.png
diff --git a/docs/static_site/src/assets/img/dev_guide_profilling_5.png b/docs/static_site/src/assets/img/dev_guide_profilling_5.png
diff --git a/docs/static_site/src/assets/img/dev_guide_profilling_6.png b/docs/static_site/src/assets/img/dev_guide_profilling_6.png
diff --git a/docs/static_site/src/assets/img/dev_guide_profilling_7.png b/docs/static_site/src/assets/img/dev_guide_profilling_7.png
diff --git a/docs/static_site/src/pages/api/api.html b/docs/static_site/src/pages/api/api.html
@@ -173,6 +173,18 @@ <h4>Deep Learning System Design Concepts</h4>
         </ul>
     </div>
 </div>
+<div class="docs-dev-guide">
+  <div class="wrapper">
+      <h2>Developer Guide</h2>
+      <ul>
+        {%- for p in site.pages -%}
+          {%- if p.category == 'Developer Guide' -%}
+            <li><a href="{{p.url | relative_url}}">{{p.title}}</a></li>
+          {%- endif -%}
+        {%- endfor -%}
+      </ul>
+  </div>
+</div>
 <div class="docs-faq">
     <div class="wrapper">
         <h2>FAQ</h2>

diff --git a/...src/pages/api/developer_guide/1_github_contribution_and_PR_verification_tips.md b/...src/pages/api/developer_guide/1_github_contribution_and_PR_verification_tips.md
@@ -0,0 +1,193 @@
+---
+layout: page_category
+title:  GitHub contribution and PR verification tips 
+category: Developer Guide
+permalink: /api/dev-guide/github_contribution_and_PR_verification_tips
+---
+<!--- Licensed to the Apache Software Foundation (ASF) under one -->
+<!--- or more contributor license agreements.  See the NOTICE file -->
+<!--- distributed with this work for additional information -->
+<!--- regarding copyright ownership.  The ASF licenses this file -->
+<!--- to you under the Apache License, Version 2.0 (the -->
+<!--- "License"); you may not use this file except in compliance -->
+<!--- with the License.  You may obtain a copy of the License at -->
+
+<!---   http://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!--- Unless required by applicable law or agreed to in writing, -->
+<!--- software distributed under the License is distributed on an -->
+<!--- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -->
+<!--- KIND, either express or implied.  See the License for the -->
+<!--- specific language governing permissions and limitations -->
+<!--- under the License. -->
+
+# GitHub contribution and PR verification tips 
+
+Use this page for general git workflow tips. 
+
+## Setup and configure
+
+It is recommended that you fork the MXNet repo, and then set the original repo as an upstream remote repo. 
+
+Fork [https://github.com/apache/incubator-mxnet](https://github.com/apache/incubator-mxnet) then:
+
+```
+git clone --recursive https://github.com/your_username/incubator-mxnet
+cd mxnet
+git remote add upstream https://github.com/apache/incubator-mxnet
+```
+
+Once `upstream` was added, then create a branch for your contribution.
+
+
+```
+git branch your-contribution-branch
+```
+
+Note that you can incorporate the changes from `upstream` to any of your local branches during or after development via: 
+
+```
+git fetch upstream
+git rebase upstream/master
+```
+
+See [this stackoverflow discussion](https://stackoverflow.com/questions/3357122/git-pull-vs-git-fetch-vs-git-rebase) for more details about difference between `git pull`, `git rebase` and `git merge`.
+
+Since Apache MXNet 3rd party git submodules, to update their changes on your branch after rebase, you can run:
+
+```
+git submodule update --recursive
+```
+
+## Save your local changes for future
+
+During development, you can save your current changes in your branch before committing anything. For example to go to another branch to do something else via:
+
+
+```
+git stash save
+```
+
+To restore the changes so that they can be added to a commit use:
+
+
+```
+git stash pop
+```
+
+
+To drop the changes, use:
+
+```
+git stash drop
+```
+
+## Reset
+
+Sometimes, if you want to wipe out the changes you have made you can use:
+
+```
+git reset --hard
+```
+
+Be very careful since hard-reset removes any of the changes and you’ll be back to the HEAD commit. To remove all the changed before a commit given its commit-SHA you can use `git reset --hard commit-SHA` or `git reset --hard HEAD~2` to remove relative to the first two commits on top of HEAD.
+
+However, sometimes it’s useful to keep the files/changes staged when moving the HEAD which can be done via 
+`git reset --soft`. All of the files changed between the original HEAD and the commit will be staged.
+
+In [summary](https://stackoverflow.com/a/50022436),
+
+
+* **`--soft`**: **uncommit** changes, changes are left staged (*index*).
+* **`--mixed`** *(default)*: **uncommit + unstage** changes, changes are left in *working tree*.
+* **`--hard`**: **uncommit + unstage + delete** changes, nothing left.
+
+
+
+## Recover a previous commit after reset
+
+Sometimes you might mistakenly reset a branch to a wrong commit. When that happens, you can use the following command to show the list of recent commits:
+
+
+```
+git reflog
+```
+
+Once you get the right hashtag, you can use git reset again to change the head to the right commit.
+
+
+## How to resolve conflict with master
+
+Sometimes when rebasing to the most recent master as explained above, git may show you there are some conflicts which it cannot resolve. These changes will not be merged. For examples, your file `conflict.py` has some conflicts with the master branch. Here you need to:
+
+* manually modify the file to resolve the conflict.
+* After you resolved the conflict, mark it as resolved by:
+
+```
+git add conflict.py
+```
+
+* Then you can continue rebase by:
+
+```
+git rebase --continue
+```
+
+* Finally push to your fork, you may need to **force push** here:
+
+```
+git push --force
+```
+
+**Note** that force push is okay when it’s on your branch and you are the only one who is using that branch. Otherwise, it can have bad consequences as it’s rewritten the history.
+
+
+## How to group multiple commits into one
+
+Sometimes, you may have added a lot of related commits suitable to be grouped/combined together to create one meaningful atomic commit. For example, when later commits are only fixes to previous ones, in your PR. 
+If you haven’t configured your default git editor, do the following once:
+
+```
+git config core.editor the-editor-you-like
+```
+
+Assume we want to merge the last 3 commits.
+
+```
+git rebase -i HEAD~3
+```
+
+1. It will pop up an text editor. Set the **first commit as pick,** and **change later ones to squash**.
+2. After you saved the file, it will pop up another text editor to ask you modify the combined commit message.
+3. Push the changes to your fork, you need to force push.
+
+```
+git push --force
+```
+
+**Note** that force push is okay when it’s on your branch and you are the only one who is using that branch. Otherwise, it can have bad consequences as it’s rewritten the history.
+
+
+## Apply only k-latest commits on to the master
+
+Sometimes it is useful to only apply your k-latest changes on top of the master. This usually happens when you have other m-commits that are already merged before these k-commits. Directly rebase against the master might cause merge conflicts on these first m-commits (which can be safely discarded).
+
+You can instead use the following command:
+
+
+```
+# k is the concrete number. Put HEAD~2 for the last 1 commit.
+git rebase --onto upstream/master HEAD~k
+```
+
+You can then force push to the master `git push --force`. Note that the above command will discard all the commits before the last k ones.
+
+
+## What is the consequence of force push
+
+The last three tips require the force push, this is because we altered the path of the commits. **It is fine to force push to your own fork, as long as the commits changed are only yours.** In case there are multiple collaborators who use your branch there is a safer option `git push --force-with-lease.`
+
+
+## PR verification
+
+When sending a pull request, remember to add some tests. During the development, one can set `MXNET_TEST_COUNT=1000/10000` to test on some randomly selected test cases. This makes the testing and development cycle faster. Moreover, some test results might change due to the seed in pseudo-random number generator. To fix the seed during testing, set `MXNET_TEST_SEED=your seed number`.
diff --git a/...te/src/pages/api/developer_guide/debugging_and_performance_optimization_tips.md b/...te/src/pages/api/developer_guide/debugging_and_performance_optimization_tips.md
@@ -0,0 +1,59 @@
+---
+layout: page_category
+title:  Debugging and performance optimization tips
+category: Developer Guide
+permalink: /api/dev-guide/debugging_and_performance_optimization_tips
+---
+<!--- Licensed to the Apache Software Foundation (ASF) under one -->
+<!--- or more contributor license agreements.  See the NOTICE file -->
+<!--- distributed with this work for additional information -->
+<!--- regarding copyright ownership.  The ASF licenses this file -->
+<!--- to you under the Apache License, Version 2.0 (the -->
+<!--- "License"); you may not use this file except in compliance -->
+<!--- with the License.  You may obtain a copy of the License at -->
+
+<!---   http://www.apache.org/licenses/LICENSE-2.0 -->
+
+<!--- Unless required by applicable law or agreed to in writing, -->
+<!--- software distributed under the License is distributed on an -->
+<!--- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY -->
+<!--- KIND, either express or implied.  See the License for the -->
+<!--- specific language governing permissions and limitations -->
+<!--- under the License. -->
+
+# Debugging and performance optimization tips
+
+The general workflow when defining your network with Gluon API is either:
+
+* build sequentially using `nn.Sequential` or `nn.HybridSequential` 
+
+* inherit from `nn.Block` or `nn.HybridBlock`
+
+## Debugging
+
+When debugging your MXNet code, remember the following:
+
+**Do NOT hybridize for debugging**
+
+The difference between [imperative style (Gluon non-hybridized) and symbolic style (Gluon hybridized)]({{ "/versions/1.2.1/architecture/program_model.html" | relative_url }}) is:
+
+* *imperative style* is _define-by-run_
+* *symbolic style* is _define-then-run_
+
+
+Basically, that means the execution path changes when calling `hybridize` on your network inherited from `HybridBlock` or `HybridSequential` (note that inheriting directly from `Block` is the same as not hybridizing your network). For efficiency, symbolic code does not keep the intermediate results and so it would be hard to debug and examine the intermediate outputs. Therefore, if you want to *examine the intermediate results for debugging, do NOT hybridize*. Once everything is working as expected, then you can `hybridize` and enjoy the speed up.
+
+Please checkout the [d2l](http://d2l.ai/chapter_computational-performance/hybridize.html?highlight=hybridize#hybrid-programming) for more details about the hybrid-programming model.
+
+## Use naive engine
+
+It is also useful to set the environment variable `MXNET_ENGINE_TYPE='NaiveEngine'` prior to running your (end-to-end) code. This setting disables multi-threading and the execution engine will be synchronous, so you can examine the backtrace more easily. Remember to change it back to either the default `'ThreadedEnginePerDevice'` or `'ThreadedEngine'`.
+
+For more details, here is a comprehensive tutorial on interactive debugging on [YouTube](https://www.youtube.com/watch?v=6-dOoJVw9_0).
+
+## Performance optimization
+
+Following up on using the environment variable `MXNET_ENGINE_TYPE` for debugging, here are the [available environment variables]({{ "/api/faq/env_var" | relative_url }})  that affect the performance of your code.
+
+Please refer to [this presentation](https://www.slideshare.net/ThomasDelteil1/debugging-and-performance-tricks-for-mxnet-gluon) for more information on debugging and performance optimization.
+