docs: Reorganize testing.md and using.md.

This is a fairly involved set of changes, including changes that:

* Delete various legacy or semi-duplicated sections of testing.md.
  Nobody needs to manually delete the postgres datbase anymore, as
  reflected in the fact that the docs still mention postgres 9.1 from
  Ubuntu Precise.
* Simplify the distracting heading section at the top of testing.md.
* Move content on manual testing to docs/development/using.md.
* Moves some content related to managing the database to
  schema-migrations.md. (Resulting in some cleanups to that page as
  well).

I ideally would have split this into smaller pieces.
This commit is contained in:
Tim Abbott
2020-01-17 00:00:09 -08:00
parent 32ff28bf24
commit 4e34f672ff
3 changed files with 122 additions and 190 deletions

View File

@@ -11,15 +11,28 @@ If you're working on authentication methods or need to use the [Zulip
REST API][rest-api], which requires an API key, see [authentication in
the development environment][authentication-dev-server].
## Common (linting and testing)
## Common
* Zulip's master branch moves quickly, and you should rebase
constantly with e.g. `git fetch upstream; git rebase
upstream/master` to avoid developing on an old version of the Zulip
codebase (leading to unnecessary merge conflicts).
* Remember to run `tools/provision` to update your development
environment after switching branches; it will run in under a second
if no changes are required.
* After making changes, you'll often want to run the
[linters](../testing/linters.md) and relevant [test
suites](../testing/testing.md). All of our test suites are designed
to support quickly testing just a single file or test case, which
you should take advantage of to save time. Consider using our [Git
pre-commit hook](../git/zulip-tools.html#set-up-git-repo-script) to
automatically lint changes when you commit them.
suites](../testing/testing.md). Consider using our [Git pre-commit
hook](../git/zulip-tools.html#set-up-git-repo-script) to
automatically lint whenever you make a commit.
* All of our test suites are designed to support quickly testing just
a single file or test case, which you should take advantage of to
save time.
* Many useful development tools, including tools for rebuilding the
database with different test data, are documented in-app at
`https://localhost:9991/devtools`.
* If you want to restore your development environment's database to a
pristine state, you can use `./tools/do-destroy-rebuild-database`.
## Server
@@ -32,24 +45,23 @@ the development environment][authentication-dev-server].
they use. You can watch this happen in the `run-dev.py` console
to make sure the backend has reloaded.
* The Python queue workers will also automatically restart when you
save changes. However, you may need to ctrl-C and then restart
`run-dev.py` manually if a queue worker has crashed.
save changes, as long as they haven't crashed (which can happen if
they reloaded into a version with a syntax error).
* If you change the database schema (`zerver/models.py`), you'll need
to use the [Django migrations
process](../subsystems/schema-migrations.md) to create and then run
your migrations; see the [new feature
tutorial][new-feature-tutorial] for an example.
process](../subsystems/schema-migrations.md); see also the [new
feature tutorial][new-feature-tutorial] for an example.
* While testing server changes, it's helpful to watch the `run-dev.py`
console output, which will show tracebacks for any 500 errors your
Zulip development server encounters.
* To manually query the Postgres database interactively, use
`./manage.py shell` or `manage.py dbshell` depending whether you
prefer an iPython shell or SQL shell.
Zulip development server encounters (which are probably caused by
bugs in your code).
* To manually query Zulip's database interactively, use `./manage.py
shell` or `manage.py dbshell`.
* The database(s) used for the automated tests are independent from
the one you use for manual testing in the UI, so changes you make to
the database manually will never affect the automated tests.
## Web
## Web application
* Once the development server (`run-dev.py`) is running, you can visit
<http://localhost:9991/> in your browser.
@@ -60,18 +72,22 @@ the development environment][authentication-dev-server].
something other than the login process.
* You can test the login or registration process by clicking the
links for the normal login page.
* If you change CSS files, your changes will appear immediately via
webpack hot module replacement.
* If you change JavaScript code (`static/js`) or Handlebars templates
(`static/templates`), the browser window will be reloaded
automatically.
* For Jinja2 backend templates (`templates/*`), you'll need to reload
the browser manually to see changes take effect.
* Most changes will take effect automatically. Details:
* If you change CSS files, your changes will appear immediately via
webpack hot module replacement.
* If you change JavaScript code (`static/js`) or Handlebars
templates (`static/templates`), the browser window will be
reloaded automatically.
* For Jinja2 backend templates (`templates/*`), you'll need to reload
the browser window to see your changes.
* Any JavaScript exceptions encountered while using the webapp in a
development environment will be displayed as a large notice, so you
don't need to watch the JavaScript console for exceptions.
* Both Chrome and Firefox have great debuggers, inspectors, and
profilers in their built-in developer tools.
* `debug.js` has some occasionally useful JavaScript profiling code.
## Mobile
## Mobile apps
See the mobile project's documentation on [using a development server
for mobile development][mobile-dev-server].