GitLab is used only for code review, issue tracking and project management. Canonical locations for source code are still https://gitweb.torproject.org/ https://git.torproject.org/ and git-rw.torproject.org.

README.md 6.11 KB
Newer Older
Hiro's avatar
Hiro committed
1 2
# Community portal

Hiro's avatar
Hiro committed
3
This is the repository of Dev portal.
Hiro's avatar
Hiro committed
4

Hiro's avatar
Hiro committed
5
To clone the code use either of
Hiro's avatar
Hiro committed
6

Hiro's avatar
Hiro committed
7
```git clone https://git.torproject.org/project/web/dev.git/```
Hiro's avatar
Hiro committed
8

Hiro's avatar
Hiro committed
9
```torify git clone http://dccbbv6cooddgcrq.onion/project/web/dev.git/```
Hiro's avatar
Hiro committed
10

Hiro's avatar
Hiro committed
11
or browse it [online](http://gitweb.torproject.org/project/web/dev.git).
Hiro's avatar
Hiro committed
12

Hiro's avatar
Hiro committed
13
## How to report bugs or feedback
Hiro's avatar
Hiro committed
14

Hiro's avatar
Hiro committed
15
Check if your issue wasn't already opened in [gitlab.torproject.org](https://gitlab.torproject.org/web/dev/issues) then open a new bug.
Hiro's avatar
Hiro committed
16 17 18 19 20 21 22 23 24 25 26 27


## What is Lektor

[Lektor](https://www.getlektor.com/) is a framework to generate and serve websites from Markdown files.

Its code can be found at [GitHub](https://github.com/lektor/lektor).

## How to contribute

### (Easy) Edit this page button

Hiro's avatar
Hiro committed
28
You can click ```Edit this page``` and submit your content changes in a [Pull Request in GitHub](https://github.com/torproject/dev/pulls).
Hiro's avatar
Hiro committed
29 30 31 32 33 34 35 36 37

### (Advanced) Compiling a local version of the website

1. Download and install Lektor: https://www.getlektor.com/downloads/

2. Install the lektor-i18n plugin and its [dependencies](https://github.com/numericube/lektor-i18n-plugin#prerequisites).

3. Clone the repository:

Hiro's avatar
Hiro committed
38
```git clone https://git.torproject.org/project/web/dev.git```
Hiro's avatar
Hiro committed
39

Hiro's avatar
Hiro committed
40
4. Init the building blocks submodule:
Hiro's avatar
Hiro committed
41 42 43 44 45 46 47 48 49 50 51 52 53

```$ cd lego && git submodule update --init --recursive```

5. Translations for the website are imported by Jenkins when bulding the page, but if you want to test them, download the correct branch of the translations repo to the ./i18n/ folder.

6. Finally

To run a local continuous builder: ```$ lektor server```

To just build the website once: ```$ lektor build -O <folder>```

#### How to develop on the website

Hiro's avatar
Hiro committed
54
Check our [wiki pages](https://dip.torproject.org/tpo/web/dev/wikis/How-to-develop-on-the-website).
Hiro's avatar
Hiro committed
55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70

### Translations

To help us to translate, please join the Tor Project team in [Transifex](https://www.transifex.com/).


### Getting help

If you want to contribute to the Community portal, we will be happy to help you. Join us at #tor-www in [irc.oftc.net](https://www.oftc.net).

## Our Workflows

### Tor Internal Workflow

This is the workflow that Tor Internal people should use when making changes on the Community Portal:

Hiro's avatar
Hiro committed
71
1. When starting work on an issue or content, please assign the issue to yourself and move into the `Doing` column on the [Community Portal Project Board](https://dip.torproject.org/web/dev/-/boards). You can follow the process outlined in ["How to send a merge request or propose a change"](https://dip.torproject.org/web/tpo/wikis/Git-flow-and-merge-requests#how-to-send-a-merge-request-or-propose-a-change) to work on your changes.
Hiro's avatar
Hiro committed
72
2. To view your changes on the website, you can [run lektor locally](https://dip.torproject.org/web/tpo/wikis/Compiling-a-local-version-of-the-website)
Hiro's avatar
Hiro committed
73
3. Once you are happy with your work, push your changes to `develop` branch and move to `needs-review` column on the [Community Portal Project Board](https://dip.torproject.org/web/dev/-/boards)
Hiro's avatar
Hiro committed
74
4. Add a comment to the issue, tagging the reviewer, e.g `@steph`, with:
Hiro's avatar
Hiro committed
75 76
    - Location of page on lektor-staging `develop` branch, e.g https://lektor-staging.torproject.org/dev/develop/
    - Contents file, containing your changes where it would be located on the **reviewer's repo** e.g `https://dip.torproject.org/steph/dev/blob/develop/content/onion-services/contents.lr`
Hiro's avatar
Hiro committed
77 78 79 80 81 82 83 84 85 86 87 88 89 90 91
    - For the review workflow, please see (Reviewer Workflow)
5. Once the work has been reviewed and any necessary changes and merge request has been made, a repo maintainer or team members with write access to gitweb master will then merge or cherry-pick these changes to master, following the workflow outlined in [How to use our git flow](https://dip.torproject.org/web/tpo/wikis/Git-flow-and-merge-requests#how-to-use-our-git-flow)
6. Merger should then move the the ticket to the `Closed` column.

### Reviewer Workflow

1. Review the page on lektor-staging
2. Review the content on your repo's develop branch and use the gitlab edit button to make any changes.
3. When you are happy with your changes:
    - Update the "Commit message" to explain why you have made your changes
    - Update the "Target Branch"
    - Make sure that the "Start a new merge request with these changes" checkbox is checked.
    - Click on "Commit changes"
4. You will be sent to a new page to create your merge request:
    - Update "Title" with a short title to explain your changes
Hiro's avatar
Hiro committed
92
    - Update "Description", you can use the commit message you entered before additionally referencing the original issue you have reviewed, e.g `https://dip.torproject.org/web/dev/issues/3` and tagging one of the repo maintainers e.g `@pili` so they know the change can be merged
Hiro's avatar
Hiro committed
93 94
    - Make sure that both "Delete source branch when merge request is accepted" and "Squash commits when merge request is accepted" are checked.
    - Click "Submit merge request"
Hiro's avatar
Hiro committed
95
5. Reviewer should comment on the original issue with a link to the merge request created, e.g `https://dip.torproject.org/steph/dev/merge_requests/2`
Hiro's avatar
Hiro committed
96 97 98 99 100

### Volunteer Workflow

This is the workflow that external volunteers should use when making changes on the Community Portal:

Hiro's avatar
Hiro committed
101
We recommend that you use our [github mirror](https://github.com/torproject/dev) to submit PRs and contributions to our Community repo. Once you have a PR ready you should:
Hiro's avatar
Hiro committed
102 103 104 105 106 107 108 109 110 111

0. Ideally try to run it locally and check that nothing breaks and everything still behaves as before
1. Make a PR and ping the team on #tor-www IRC channel to let us know there's a PR waiting for review

At this point, one of us on the website team will aim to review your PR within 24h during the week (this may take longer on the weekends). Review will involve:

  - Reading the text to make sure it's accurate and there are no spelling errors or grammar mistakes
  - If there are any front end and/or template changes involved, the changes will be pushed to our `develop` branch for functionality review
  - If there are any fixes necessary, we will ask for changes to be made.

Hiro's avatar
Hiro committed
112
Once it all looks good and behaves correctly, we will merge your request to the master branch of the dev portal [canonical repo](https://gitweb.torproject.org/project/web/dev.git/) on [gitweb](https://gitweb.torproject.org/) master.