paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-11-05 22:43:42 +00:00
Code Issues Packages Projects Releases Wiki Activity

Remove largely obsolete documentation pages.

Browse Source 
(imported from commit eb02c24dd25a12a5676b5e52c914993650f73aa6)
This commit is contained in:
Tim Abbott
2015-09-22 22:30:55 -07:00
parent 1be909a450
commit a3c122eb41
3 changed files with 0 additions and 172 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/index.rst
View File

@@ -11,12 +11,10 @@ Contents:
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
welcome
new-feature-tutorial new-feature-tutorial
code-style code-style
directory-structure directory-structure
testing testing
schema-changes
Indices and tables Indices and tables
================== ==================

131
docs/schema-changes.rst
View File

@@ -1,131 +0,0 @@
==============
Schema changes
==============
If you are making a change that requires a database schema upgrade,
there are a few extra things you need to keep in mind.
Using South for migrations
--------------------------
1. Discuss the change informally with your team.
#. Edit ``zerver/models.py`` for your particular class.
* See notes below about keep\_default.
#. Run ``./manage.py schemamigration zerver --auto``
* This will create the ``000#_***.py`` schema migration file in
``zerver/migrations``.
#. Read `Notes and Cautions`_ section below, as you may need to edit
the migration. A common step here is setting keep\_default to True.
#. Do ``git add`` with your new migration.
#. Run ``./manage.py migrate zerver``.
#. Write supporting code or otherwise validate the DB change locally.
TODO: Advice on testing schema changes?
#. Commit your changes:
a. The migration must be in the same commit as the models.py changes.
#. Include [schema] in the commit message.
#. Include [manual] in the commit message if additional steps are
required.
#. Before deploying your code fix, read the notes on `Deploying to
staging`_.
Deploying to staging
--------------------
Always follow this process.
1. Schedule the migration for after hours.
#. For long-running migrations, double check that you use appropriate
library helpers in ``migrate.py`` to ensure that changes happen in small
batches that are committed frequently.
#. Announce that you are doing the migration to your team, to avoid
simultaneous migrations and other outcomes of poor communication.
#. Do any administrative steps, such as increasing
checkpoint\_segments.
#. Apply the migration in advance from staging, using commands similar
to the following, where ``[your commit]`` is the commit that has your
migration::
cd ~/zulip
git fetch
cd /tmp
git clone ~/zulip
cd zulip
git checkout [your commit]
./manage.py migrate zerver
cd /tmp
rm -Rf zulip
#. Undo any temporary administrative changes, such as increasing
checkpoint\_segments.
Because staging and prod share a database, for most migrations, nothing
special needs to be done when deploying to prod since the shared
database schema will have already been updated, but in some cases some
code to properly initialize data structures may need to be run.
Migrating to a new schema
-------------------------
When doing a git pull and noticing a [schema] commit, you must manually
perform a schema upgrade: ``./manage.py migrate zerver``.
``generate-fixtures`` should automatically detect whether
the schema has changed and update things accordingly.
Notes and Cautions
------------------
**Large tables**
For large tables like Message and UserMessage, you
want to take precautions when adding columns to the table, performing
data backfills, or building indexes. We have a ``migrate.py`` library to
help with adding columns and backfilling data. For building indexes,
we should do this outside of South using postgres's CONCURRENTLY
keyword.
**Numbering conflicts across branches**
If you've done your schema change in a branch, and meanwhile another
schema change has taken place, South will now have two migrations with
the same number. To fix this, delete the migration file that South
generated, and re-run ``./manage.py schemamigration zerver --auto``.
**Avoid nullables**
You generally no longer need a Nullable column
to avoid problems with staging and prod not having the same models.
See the next point about setting ``keep_default=True``.
**Use keep\_default**
When adding a new column to an existing table,
you almost always will want to set ``keep_default=True`` in the South
migration ``db.add_column`` call. If you don't, everything will
appear to work fine in testing and on staging, but once the schema
migration is done, the pre-migration code running on prod will be
unable to save new rows for that table (so e.g. if you were adding a
new field to UserProfile, we'd be unable to create new users). The
exception to this rule is when your field default is not a constant
value. In this case, you'll need to do something special to either
set a database-level default or use a Nullable field and a multi-step
schema deploy process.
**Rebase pain**
If you ever need to rebase a schema change past
other schema changes made on other branches, in addition to
renumbering your schema change, youalso need to be sure to regenerate
at least the bottom part of your migration (which shows the current
state of all the models) after rebasing; if you don't, then the next
migration made after your migration is merged will incorrectly
attempt to re-apply all the schema changes made in the migration you
skipped. This can be potentially dangerous.
**Upstreaming**
We recommend upstreaming schema changes as soon as possible to
avoid schema numbering conflicts (see above).

39
docs/welcome.rst
View File

@@ -1,39 +0,0 @@
========
Welcome!
========
This document will guide you through getting started on Zulip development.
Installation
============
You should clone the Zulip git repository onto a Linux or OS X machine.
Then follow the instructions in README.dev.
Running the development server
==============================
After installing, you will have a virtual machine serving a development Zulip instance.
To start it, simply run `vagrant up` and navigate to `http://localhost:9991/`__ in
your browser. Behind the scenes, this is running `run-dev.py` via `supervisor`.
Viewing the server log
----------------------
Sometimes things go wrong when you change backend code. The server logs are stored
in `/var/logs/supervisor/zulip-dev-stdout---supervisor-******.log`.
Restarting run-dev.py
---------------------
Most of the time, the server will refresh when you change underlying python
files or style sheets, but sometimes you might need to restart the server
(for example, if you have a syntax error or need to change the database schema).
To do so, use `sudo supervisorctl restart zulip-dev`.
Making changes
==============
.. attention::
We need to determine our final development workflow