search

translate / pootle

Online translation tool
http://pootle.translatehouse.org
GNU General Public License v3.0
1.49k stars 287 forks source link

Improve 'Hacking' documentation #5103

Open iafan opened 8 years ago

iafan commented 8 years ago

I've been setting up Pootle on a new VM with latest Ubunty 16.04 by following instructions on http://docs.translatehouse.org/projects/pootle/en/latest/developers/hacking.html and http://docs.translatehouse.org/projects/pootle/en/latest/developers/frontend.html and found some issues along the process that I think worth reporting.

Running $ pip install -r requirements/dev.txt gives errors during missing dev libraries. I had to run it multiple times, each time researching what else is missing. I think it makes sense to mention that some modules (especially lxml) might require compiling from sources, so a clean Linux might require some development version of libraries. This is what Ubuntu 16.04 needs:

$ sudo apt install libxml2-dev libxslt1-dev python-dev libz-dev

When running $ python manage.py migrate step, I've got the error: redis.exceptions.ConnectionError: Error 111 connecting to 127.0.0.1:6379. Connection refused.. So Redis needs to be installed and running before running this command, but there's no information about installing Redis before this step.

The $ python manage.py initdb command not only initializes the database as one would guess from its name, but also does an initial import of sample projects, which took more than 10 minutes for me. Of course one can run $ python manage.py initdb --no-projects, but I wish I knew this beforehand. I'd also suggest for initdb not to do any import at all by default. At the end of initialization it might suggest to run $ python manage.py update_stores to import those sample projects.

Once the initdb step is completed, the following message is shown:

Successfully populated the database. To create an admin user, use the pootle createsuperuser command.

However, it is not very clear whether this step is optional or not. Also in development version the command will be rather $ python manage.py createsuperuser.

Once I run $ python manage.py runserver it reports the following issue:

?: (pootle.W001) No RQ Worker running. HINT: Run new workers with manage.py rqworker

But there's no information in the hacking doc on how to run an RQ worker and why it is needed. Might make sense to add this step before runserver one.

The fact that one needs to also perform steps from "Frontend development" section is subtle: no one can do front-end development before installing Pootle; no one can run Pootle for back-end development before installing dependencies from "Frontend development" section. I'd recommend merging relevant part of the "Frontend development" page on installing prerequisites and building assets into the main "Hacking" doc.

After running $ ./manage.py webpack --dev I've got the error: /usr/bin/env: ‘node’: No such file or directory. The official and the easiest way to install NodeJS and npm on Ubuntu is:

$ sudo apt install nodejs npm

However, the installed binary is now called nodejs, not node. So one have to rather install legacy NodeJS, which is counter-intuitive:

$ sudo apt install nodejs-legacy

(or we need to update Pootle to use nodejs binary).

There's a missing step that needs to be added to the docs:

$ python manage.py compilejsi18n

Now when one starts the server and tries to log in as a superuser, they need to activate their account. This particular issue is reported separately: #5094

unho commented 8 years ago

I think it makes sense to mention that some modules (especially lxml) might require compiling from sources, so a clean Linux might require some development version of libraries.

It is assumed you have http://docs.translatehouse.org/projects/pootle/en/latest/server/requirements.html So yes, it is worth adding a link in hacking docs to there.

So Redis needs to be installed and running before running this command

Yes, also in the link above.

The $ python manage.py initdb command not only initializes the database as one would guess from its name, but also does an initial import of sample projects

Makes sense.

Successfully populated the database. To create an admin user, use the pootle createsuperuser command.

However, it is not very clear whether this step is optional or not. Also in development version the command will be rather $ python manage.py createsuperuser.

We can rephrase to "You must create an admin user, use the pootle createsuperuser command.". Regarding the pootle command I would put some note in the hacking doc.

But there's no information in the hacking doc on how to run an RQ worker and why it is needed. Might make sense to add this step before runserver one.

Hacking doc was left behind when updating the installation docs, so it make sense review the latter and maybe pick some missing stuff.

I'd recommend merging relevant part of the "Frontend development" page on installing prerequisites and building assets into the main "Hacking" doc.

Duplicating it won't help at all in maintaining it. I would instead rephrase hacking to clearly point there.

dwaynebailey commented 8 years ago

@iafan probably best to PR changes that would need to be made. Otherwise, honestly, one of us is just going to have to replicate exactly what you've just learnt and what you are now an expert on to sort out the missing notes :) The install docs are in good shape because we simply PR'd fixes as we hit them, that's the best way to fix the hacking docs.