README.md
3d0e13aa
 # How to contribute
 
deb20ef5
 Thanks for being interested to work on the website, I tried to make a simple
e547d2e2
 how-to for you to quickly get you setup:
3d0e13aa
 
 __Step 1:__ Clone the git repo.
 
     git clone https://git.torproject.org/project/web/webwml.git
     cd webwml
 
deb20ef5
 __Step 1b:__ Create a bare public repository (i.e on Github), where you'd push
e547d2e2
 your commits to. Make sure you're in `webwml` directory, and run:
3d0e13aa
 
     git remote add pick-a-name your-git-url
 
 _Example:_
c48c6e36
     `git remote add tpo-gh git@github.com:mrphs/tpo.git`
3d0e13aa
 
 __Step 2:__ Create and switch to a new branch.
 
deb20ef5
 _In the following example, I've named my branch "docs" as I'm planning to work
e547d2e2
 on the documentations._
3d0e13aa
 
     git checkout -b docs
 
deb20ef5
 __Step 3:__ Now you can start working on website and make changes. Once you're
e547d2e2
 done, commit and push it to your public repo.
3d0e13aa
 
 _Example:_
 
     git push tpo-gh docs
 
deb20ef5
 __Step 4:__ Open a new ticket on [trac](https://trac.torproject.org) with a
e547d2e2
 link to your shiny new repo/branch.
3d0e13aa
 
eac58385
 # Building website
 Torproject website is being built and published automatically.
 To quickly get set up and build website locally, simply follow these steps:
43377598
 
331982f8
  __Step 1:__ Get the website's build dependencies.
43377598
 
331982f8
     sudo apt-get install wml asciidoc
 
deb20ef5
   __Step 2:__ Configure where to find your tor git repository. It needs this
e547d2e2
 to make the
43377598
      manual page.
 
331982f8
     git clone https://git.torproject.org/project/web/webwml.git
     cd webwml
     cp Makefile.local.sample Makefile.local
deb20ef5
 
331982f8
 Note: Change the `TORGIT` in Makefile.local to point to your tor git repo.
43377598
 
331982f8
   __Step 3:__ Make the website.
43377598
 
331982f8
     make
43377598
 
 You should now be able to point your browser at the locally generated site...
 
331982f8
     file:///home/atagar/Desktop/tor/webwml/getinvolved/volunteer.html.en
 
43377598
 
331982f8
 ### Troubleshooting the build
43377598
 
331982f8
 The build fails with "Invalid object name".
43377598
 
   If you get an error like...
 
     ---- Contents of STDERR channel: ---------
     fatal: Invalid object name 'tor-0.2.6.1-alpha'.
     asciidoc: FAILED: manpage document title is mandatory
deb20ef5
     No manpage because of asciidoc error or file not available from git at
e547d2e2
     /tmp/wml.zwcq0q/wml.30867.tmp1.wml line 415.
43377598
 
deb20ef5
   This means your tor repository is out of date. Update your tor git
e547d2e2
 repository.
43377598
 
deb20ef5
 ### Some information regarding working with minified CSS and JS sources
 
 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.
 
 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.
331982f8
 
 ### More detailed instructions from Roger
 
deb20ef5
 _Note: This section was written when website repo was still on svn, and it
e547d2e2
 wasn't built automatically._
43377598
 
81f0fb78
 Here are the instructions I sent David Fifield when he asked about
 editing the website. I hope they are useful for you too! --Roger
 
87ab12b7
 Copy Makefile.local.sample to Makefile.local in your webwml/ directory.
 Point TORGIT to a tor git.
81f0fb78
 
 Then apt-get install wml and (alas) probably a shocking number of other
 debs. Then you can type 'make' and it will build the website for you
 locally. It's probably a smart move to see whether 'make' works before
87ab12b7
 you git commit any changes to the wml files.
81f0fb78
 
 You can edit docs/en/pluggable-transports.wml (and that is
 the right source file to edit, not the html). But go take a
 look at that file. You'll notice it has a bunch of tags like
4d71689c
 <version-torbrowserbundle>. If you're just bumping version
81f0fb78
 numbers, you probably just want to change the definition of those tags.
 They're in include/versions.wmi
 
 (Every once in a while you may need to edit pluggable-transports.wml
 too -- generally when you change the file name so drastically that just
 changing the versions.wmi tags isn't enough.)
 
40bfc7e4
 Pushes to the master branch of the git repository will cause the
87ab12b7
 website to get re-built and published. Pushing to the staging branch
40bfc7e4
 will update www-staging.torproject.org.
81f0fb78
 
 Alas, https://www.torproject.org/dist/ isn't in version control. You
87ab12b7
 write to it by ssh'ing to dist-master.torproject.org and going to
40bfc7e4
 /srv/dist-master.torproject.org/htdocs/ and then sticking your stuff
 there. When you want it to go live, you run
87ab12b7
 "static-update-component dist.torproject.org" on dist-master.
81f0fb78
 
 Weasel has hopes that somebody will write some scripts to make maintaining
 packages in dist/ less awful -- automatically check that they have
 signatures and that the sigs match, that the items on the website are in
 fact in dist, only allow certain people to put files in certain places,
 etc. One day! :)
6c738818
 # tp_donation