docs: improve docs, add random.md

README.md

@@ -2,10 +2,32 @@
 
 ![img](https://repository-images.githubusercontent.com/180590388/968e6880-6538-11e9-9da6-4aef78157e94)
 
+## Repository Structure
+
+* **[`ci`](ci/)**: Gitlab CI configuration files
+* **[`common/defs`](common/defs/)**: JSON coin definitions and support tables
+* **[`common/protob`](common/protob/)**: Common protobuf definitions for the Trezor protocol
+* **[`common/tools`](common/tools/)**: Tools for managing coin definitions and related data
+* **[`core`](core/)**: Trezor Core, firmware implementation for Trezor T
+* **[`crypto`](crypto/)**: Stand-alone cryptography library used by both Trezor Core and the Trezor One firmware
+* **[`docs`](docs/)**: Assorted documentation
+* **[`legacy`](legacy/)**: Trezor One firmware implementation
+* **[`python`](python/)**: Python [client library](https://pypi.org/project/trezor) and the `trezorctl` command
+* **[`storage`](storage/)**: NORCOW storage implementation used by both Trezor Core and the Trezor One firmware
+* **[`tests`](tests/)**: Firmware unit test suite
+* **[`tools`](tools/)**: Miscellaneous build and helper scripts
+* **[`vendor`](vendor/)**: Submodules for external dependencies
+
+
 ## Contribute
 
 Inspired by [GitLab Contributing Guide](https://docs.gitlab.com/ee/development/contributing/)
 
+Make sure to check out general [contribution guidelines](https://wiki.trezor.io/Developers_guide:Contributing) on the Trezor Wiki. If you are contributing to Trezor Core
+(the Trezor T firmware), make sure to check out [Trezor Core contribution guidelines](core/docs/CONTRIBUTING.md) as well.
+
+Some useful [assorted knowledge](docs/random.md) can be found in the `docs` subdirectory.
+
 ### Security vulnerability disclosure
 
 Please report suspected security vulnerabilities in private to [security@satoshilabs.com](mailto:security@satoshilabs.com), also see [the disclosure section on the Trezor.io website](https://trezor.io/security/). Please do NOT create publicly viewable issues for suspected security vulnerabilities.

core/docs/CONTRIBUTING.md

@@ -5,8 +5,9 @@ Please read the general instructions you can find on our [wiki](https://wiki.tre
 In this repository your Pull request should follow these criteria:
 
 - The code is properly tested.
-- Tests must pass on [CI](https://travis-ci.org/trezor/trezor-core).
+- Tests must pass on [CI](https://travis-ci.org/trezor/trezor-firmware).
 - The code is properly formatted. The make command `make style_check` checks if it is so and you can use `make style` to make it happen.
+- Generated files are up-to-date. Use `make gen` in repository root to make it happen.
 - Commits must have concise commit messages, the imperative mood is preferred ([rationale](https://gist.github.com/robertpainsi/b632364184e70900af4ab688decf6f53)).
 - Multiple commits per PR are allowed, but please do not use reverts etc. - use interactive rebase.
 Do not use merge (e.g. merge trezor/master into...). Again, use rebase.

docs/random.md

@@ -0,0 +1,34 @@
+# Assorted knowledge
+
+This file serves as a dumping ground for important knowledge tidbits that do not clearly
+fit in any particular location. Please add any information that you think should be
+written down.
+
+At any time, information stored here might be restructured or moved to a different
+location, so as to ensure that the documentation is well structured overall.
+
+
+### Generated files
+
+Certain files in the repository are auto-generated from other sources, but the generated
+content is stored in Git. The command `make gen_check`, run from CI, ensures that the
+generated content matches its sources. The command `make gen` regenerates all relevant
+files.
+
+In general, generated files are not compatible between branches. After rebasing or
+merging a different branch, you should immediately run `make gen` and make sure the
+result is commited.
+
+**Do not fix merge conflicts in generated files**. Instead, run `make gen` and commit
+the result.
+
+The following is a (possibly incomplete) list of files regenerated by `make gen`:
+
+* `core/mocks/generated`: mock Python stubs for C modules (`modtrezor*`). Generated from
+  special comments in `embed/extmod/modtrezor*`.
+* `networks.py`, `tokens.py`, `coininfo.py` and `nem_mosaics.py` in their respective
+  subdirectories of `core/src/apps`. In general, any file matching `*.py.mako` has a
+  corresponding `*.py` file generated from the Mako template. These files are based on
+  coin data from `common/defs`.
+* Protobuf class definitions in `core/src/trezor/messages` and
+  `python/src/trezorlib/messages`. Generated from `common/protob/*.proto`.