improved monorepo docs

README.md

@@ -271,6 +271,20 @@ In order to add a new workspace, one should create a new directory under `packag
 
 Suggested way to add a new dependency to an existing workspace is to run `yarn workspace <workspace name> add <package name>` instead of just `yarn add <package name>`. For example, run `yarn workspace cbioportal-frontend add lodash` instead of `yarn add lodash`. Similarly to remove a package run `yarn workspace <workspace name> remove <package name>`.
 
+### Tips for dependency management
+
+Since now all the packages live under a single repository it might be confusing how to import different modules into the file you're working on.
+
+If you are working on `cbioportal-frontend` repository feel free to import any module from any package under `packages`. When importing from internal packages always use import statements like `import {something} from 'cbioportal-frontend-commons'`. Never do under any circumstances something like `import {something} from ../../packages/cbioportal-frontend-commons/src/lib/someLib` or `import {something} from ../../packages/react-mutation-mapper/src/component/someComponent`. Treat internal packages like any other npm package you would import.
+
+Avoid circular dependencies at all costs. For example, while it is okay to import a module from `cbioportal-frontend-commons` in `react-mutation-mapper`, there should not be any imports from `react-mutation-mapper` in `cbioportal-frontend-commons`. If you happen to need some component from from `react-mutation-mapper` in `cbioportal-frontend-commons`, consider moving that component into `cbioportal-frontend-commons` package.
+
+Last but not least, never ever import anything from `cbioportal-frontend` package in packages under the `packages` directory.
+
+### Updating existing packages
+
+Whenever you need to update code under packages, you should also consider updating the version number in the corresponding `package.json` as well as the dependencies of other packages depending on the package you updated. For example if you update the `cbioportal-frontend-commons` version from`0.1.1` to `0.1.2`, corresponding `cbioportal-frontend-commons` dependency in the `package.json` for `react-mutation-mapper` and `cbioportal-frontend` should also be updated to the new version.
+
 ## Components
 
 Components under `packages` should only depend on either external node modules or workspaces under `packages`.