tor-webwml.git

README.md   1) # How to contribute
README.md   2) 

README.md   3) Thanks for being interested to work on the website, I tried to make a simple

README.md   4) how-to for you to quickly get you setup:

README.md   5) 
README.md   6) __Step 1:__ Clone the git repo.
README.md   7) 
README.md   8)     git clone https://git.torproject.org/project/web/webwml.git
README.md   9)     cd webwml
README.md  10) 

README.md  11) __Step 1b:__ Create a bare public repository (i.e on Github), where you'd push

README.md  12) your commits to. Make sure you're in `webwml` directory, and run:

README.md  13) 
README.md  14)     git remote add pick-a-name your-git-url
README.md  15) 
README.md  16) _Example:_

README.md  17)     `git remote add tpo-gh git@github.com:mrphs/tpo.git`

README.md  18) 
README.md  19) __Step 2:__ Create and switch to a new branch.
README.md  20) 

README.md  21) _In the following example, I've named my branch "docs" as I'm planning to work

README.md  22) on the documentations._

README.md  23) 
README.md  24)     git checkout -b docs
README.md  25) 

README.md  26) __Step 3:__ Now you can start working on website and make changes. Once you're

README.md  27) done, commit and push it to your public repo.

README.md  28) 
README.md  29) _Example:_
README.md  30) 
README.md  31)     git push tpo-gh docs
README.md  32) 

README.md  33) __Step 4:__ Open a new ticket on [trac](https://trac.torproject.org) with a

README.md  34) link to your shiny new repo/branch.

README.md  35) 

README.md  36) # Building website
README.md  37) Torproject website is being built and published automatically.
README.md  38) To quickly get set up and build website locally, simply follow these steps:

README     39) 

README.md  40)  __Step 1:__ Get the website's build dependencies.

README     41) 

README.md  42)     sudo apt-get install wml asciidoc
README.md  43) 

README.md  44)   __Step 2:__ Configure where to find your tor git repository. It needs this

README.md  45) to make the

README     46)      manual page.
README     47) 

README.md  48)     git clone https://git.torproject.org/project/web/webwml.git
README.md  49)     cd webwml
README.md  50)     cp Makefile.local.sample Makefile.local

README.md  51) 

README.md  52) Note: Change the `TORGIT` in Makefile.local to point to your tor git repo.

README     53) 

README.md  54)   __Step 3:__ Make the website.

README     55) 

README.md  56)     make

README     57) 
README     58) You should now be able to point your browser at the locally generated site...
README     59) 

README.md  60)     file:///home/atagar/Desktop/tor/webwml/getinvolved/volunteer.html.en
README.md  61) 

README.md  62) For details on WML see
README.md  63) http://www.shlomifish.org/open-source/projects/website-meta-language/

README     64) 

README.md  65) ### Troubleshooting the build

README     66) 

README.md  67) The build fails with "Invalid object name".

README     68) 
README     69)   If you get an error like...
README     70) 
README     71)     ---- Contents of STDERR channel: ---------
README     72)     fatal: Invalid object name 'tor-0.2.6.1-alpha'.
README     73)     asciidoc: FAILED: manpage document title is mandatory

README.md  74)     No manpage because of asciidoc error or file not available from git at

README.md  75)     /tmp/wml.zwcq0q/wml.30867.tmp1.wml line 415.

README     76) 

README.md  77)   This means your tor repository is out of date. Update your tor git

README.md  78) repository.

README     79) 

README.md  80) ### Some information regarding working with minified CSS and JS sources
README.md  81) 

README.md  82) If you want to edit any of the CSS or JS sources, please bear in mind that the HTML uses the minified versions. We keep in the repository both versions side-to-side. Once you edit the original source make sure you generate the minified version again. Most editors have plugins to minify CSS and JS files. On Debian it is possible to install the yui-compressor package and use it as follows:
README.md  83) 
README.md  84) 
README.md  85)     yui-compressor myfile.js -o myfile-min.js
README.md  86) 

README.md  87) 
README.md  88) If you are wondering why is it "cool" to minify sources even though compression is used on the server, please consider that Minification can be well be used in combination with gzipping sources. Minification does a lot of additional things that compression doesn't do. During minification comments are removed, long variables are renamed to shorter variable names, etc. Transferred data can be significantly smaller after minification, than by simply compressing the original. Although this depends a lot on the original source, minifying helps with mobile browsers and slower connections.

README.md  89) 
README.md  90) ### More detailed instructions from Roger
README.md  91) 

README.md  92) _Note: This section was written when website repo was still on svn, and it

README.md  93) wasn't built automatically._

README     94) 

README     95) Here are the instructions I sent David Fifield when he asked about
README     96) editing the website. I hope they are useful for you too! --Roger
README     97) 

README     98) Copy Makefile.local.sample to Makefile.local in your webwml/ directory.
README     99) Point TORGIT to a tor git.

README    100) 
README    101) Then apt-get install wml and (alas) probably a shocking number of other
README    102) debs. Then you can type 'make' and it will build the website for you
README    103) locally. It's probably a smart move to see whether 'make' works before

README    104) you git commit any changes to the wml files.

README    105) 
README    106) You can edit docs/en/pluggable-transports.wml (and that is
README    107) the right source file to edit, not the html). But go take a
README    108) look at that file. You'll notice it has a bunch of tags like

README    109) <version-torbrowserbundle>. If you're just bumping version

README    110) numbers, you probably just want to change the definition of those tags.
README    111) They're in include/versions.wmi
README    112) 
README    113) (Every once in a while you may need to edit pluggable-transports.wml
README    114) too -- generally when you change the file name so drastically that just
README    115) changing the versions.wmi tags isn't enough.)
README    116) 

README    117) Pushes to the master branch of the git repository will cause the

README    118) website to get re-built and published. Pushing to the staging branch

README    119) will update www-staging.torproject.org.

README    120) 
README    121) Alas, https://www.torproject.org/dist/ isn't in version control. You

README    122) write to it by ssh'ing to dist-master.torproject.org and going to

README    123) /srv/dist-master.torproject.org/htdocs/ and then sticking your stuff
README    124) there. When you want it to go live, you run

README    125) "static-update-component dist.torproject.org" on dist-master.

README    126) 
README    127) Weasel has hopes that somebody will write some scripts to make maintaining
README    128) packages in dist/ less awful -- automatically check that they have
README    129) signatures and that the sigs match, that the items on the website are in
README    130) fact in dist, only allow certain people to put files in certain places,
README    131) etc. One day! :)