Commit ebebb5d7 authored by Diogo Sergio's avatar Diogo Sergio
Browse files

[REPO] - Updated README / WIP

parent 280ad227
.DS_Store
## The Tor Project Design Team
(Description of the design team, ux, research, areas of responsibility, activities, history?)
## Design workflow
(Description of the design workflow, trac, dip, tickets, teams, projects, gitflow design)
## Table of contents
* [Gitflow Design](#gitflow-design)
* [Overview](#overview)
* [Main Branches](#main-branches)
* [Supporting Branches](#supporting-branches)
* [How to Contribute](#how-to-contribute)
* [Prerequisites](#prerequisites)
* [Software Recommendations](#software-recommendations)
* [Folder Structure](#folder-structure)
* [Getting Started Guides](#getting-started-guides)
* [Contact](#contact)
## Gitflow-Design
Gitflow-design is a git workflow for designers and design work. It's meant to be open, platform agnostic and looking to minimise dependencies on proprietary software to help increase collaboration. The workflow itself is essentially a set of procedures that every team member has to follow in order to come to a design process.
By using git, we get to take advantage of a lot of useful features available such as controlled access, review process, feedback system, version control files, preview changes in context with side-by-side diffs, detailed history of changes and more.
### Overview
Gitflow-design is a git branching model and at its core, there are two main branches to record the history, **master** and **design**, which are followed by supporting branches. We will explain more about this bellow, but here is a diagram overview of the workflow.
Please register or sign in to reply
<p align="center"><img src="/imgs/gitflowdesigndiagram.png" width="90%"></p>
### Main Branches
**master**, **design**
Instead of a single master branch, this workflow uses two main branches to record the history as mentioned above. The **master** branch stores all the signed off releases from the design branch, and the **design** branch serves as an integration branch for the **ux** and **ui** supporting branches. All merge requests from supporting branches are only merged into design after being reviewed and approved by the design team.
### Supporting Branches
**ux/feature**, **ui/feature**
There are two types of feature branches, one for the user experience work with the prefix **ux/** and the other for visual design work with the prefix **ui/**. Ideally one leads to the other, but in some cases they might be done at the same time, so they can also be represented by the prefix **uxui/**.
**Example:**
We have an upcoming task to redesign the tor download page. To kickoff this work, a ux feature branch is created and named **ux/downloadpage**, and this is where the ux work will happen. Once the work has been done the designer will create a merge request to the design branch and start the review process. If the reviewers are happy with the work, the merge request is accepted and the branch **ux/downloadpage** is merged into design.
At this point the **ux/downloadpage** is ready to progress into ui design, so it starts in the same way as ux, with the creation of a ui feature branch named **ui/downloadpage** *(notice the ui prefix this time)* and the process is the same. The designer will work on the task and create a merge request when the work is ready for review.
Let's say both ui and ux branches were merged into design, this means the work for this task is finalised and its ready to be implemented. So the last action required is for a member of the design team to merge the design branch *(with both ux and ui work inside)* into the master branch. Keep in mind that all the work in the master branch should be ready to be picked for development.
You can read the step by step guide on how to follow this workflow in git further down the page.
## How to Contribute
🎉 First things first, thanks for showing interest in contributing to the tor project! 🎉
This workflow is still work in progress and we are still experimenting with it, so if you have any suggestions on how to improve it, please get in touch!
### Prerequisites
* Git - [https://git-scm.com/](https://git-scm.com/) - If you plan to use the terminal to interact with git.
### Software Recommendations
We want to keep the workflow open to anyone who wants to contribute, so we focus on using open file formats that can easily be accessed by others and are not dependant on proprietary software.
**Design software:**
* Inkscape (Vector graphics editor) - https://inkscape.org/ - Free / Open Source
* GIMP (Image editor) - https://www.gimp.org/ - Free / Open Source
**Git - GUI clients:**
* Sourcetree - [https://www.sourcetreeapp.com/](https://www.sourcetreeapp.com/) - Free / Proprietary
* Github* - [https://github.com/](https://github.com/) - Free / Open Source **(Will need work-arounds to work with Gitlab)*
* Other git GUIs - [https://git-scm.com/downloads/guis](https://git-scm.com/downloads/guis) - More clients, choose at your own will.
### Folder Structure
This is an example of the folder structure being used to keep things organised and manageable for all of us.
.
├── images # Images to support this repository
└── project # Project folder (e.g.: web)
└── task/feature # Task or feature folder
├── ux # User experience work
│   ├── exports # Exported artboards
│   └── source # Source files
│    ├── *sketch # Editable file being used *sketch as an example
   │    └── svg # Open format alternative
└── ui # User interface work
├── exports # Exported assets
└── source # Source files
├── *psd # Editable file being used *psd as an example
└── xcf  # Open format alternative
***Important***:
When using proprietary software, please make sure you always keep copies of the editable file in open file formats. For example if you use Sketch, keep the .sketch file in the source, but also export all your artboards into separate .svg files.
### Getting Started Guides
### Terminal
If you're quite comfortable with command line applications and prefer to interact with git that way, then this will give you an overview on how to do it.
#### Step 1 - Clone the Project Repository
```bash
# Open the directory to where you want to download the repository.
$ cd ~Documents
# Clone the design repository.
$ git clone git@gitlab.torproject.org:torproject/ux/design.git
# Go into its directory.
$ cd design
```
#### Step 2 - Switch to the Design Branch
```bash
# You're now in the master branch, so let's switch to the design branch.
$ git checkout design
```
#### Step 3 - Create a Task/Feature Branch
```bash
# Always create task/feature branches based on design and use prefixes accordingly ux/, ui/ or uxui/.
# Name should follow prefix/name, replace accordingly. e.g.: ux/downloadpage,
$ git checkout -b ux/name
```
#### Step 4 - Work on The Task
```bash
# At this point you are ready to start working.
# Make sure you follow the correct folder structure when creating your files.
# Check the status of the current branch, after working on it.
$ git status
```
#### Step 5 - Add and Commit Changes
When you finish a design iteration and are ready to show it to gather feedback, you will have to commit your work, so it can be pushed to gitlab for everyone to see. Commit titles should start with [UX] or [UI] accordingly to the work they include and a couple words describing the scope of the work.
Keep in mind that you can commit multiple times.
```bash
# First you need to add the work and changes, you have just made.
# -A stands for --All.
$ git add -A
# Now that the files are added, you can commit them.
# The title should include the prefix followed by the scope of the work.
# E.g.: '[UX] - Download Page Redesign'
$ git commit -m '[UX] - Short Description of the Work'
```
#### Step 6 - Push Changes to git
After you commit, the work is still only available locally on your machine, to make it available for everyone to see, you will have to push this commit to git.
```bash
# You have to push them up-stream (-u) to origin. E.g. git push -u origin ux/downloadpage
$ git push -u origin ux/name
```
#### Step 7 - Merge Request
If your work is now finalised and you have committed and pushed it, the last step is to get it reviewed by the design team. In order to do this, you will have to create a **merge request**.
To do this, simply open [https://gitlab.torproject.org/torproject/ux/design](https://gitlab.torproject.org/torproject/ux/design) and if you pushed recently you will see a message at top of the page announcing it with a button to create a merge request. Just click that button to open the merge request interface and follow the steps.
If you have pushed the work sometime ago, do the same and open [https://gitlab.torproject.org/torproject/ux/design](https://gitlab.torproject.org/torproject/ux/design) and click on *Merge Requests* on the left side menu and then *New Merge Request*, and this will open the merge request interface and now just follow the steps.
***Please make sure you select the source branch as your own, and the target branch as design.***
#### Step 8 - Celebrate! 🎉🎉
You have just made your first contribution to the tor project!
## Contact
* IRC: #tor-ux on OFTC Network - [https://www.oftc.net/](https://www.oftc.net/)
  • @antonela I've pushed a first pass at the README (WIP), but have a read through and let me know what you think. There are a couple sections that I could use some help with:

    The Tor Project Design Team (Description of the design team, ux, research, areas of responsibility, activities, history?)

    Design workflow (Description of the design workflow, trac, dip, tickets, teams, projects?)

    Edited by Diogo Sergio
  • Great work! In your FOSDEM presentation I saw that you also had a folder for user research. Do you think in this case we should keep it separate?

  • Hi @pili!

    I took it out because we have the https://gitlab.torproject.org/torproject/ux/research already in place, and I didn't know the plans of vision for that one.

    But we have options, we can merge them both into this one, or we can also run gitflow in that one and keep things separate. I think both work! It's up to us to decide.

    What do you think?

  • I spoke with @antonela and we've decided to keep it in a separate repo for now. We can look at running gitflow in the research repo once we have it working in design :)

    Thanks for working on this!

  • Sounds good! :)

  • mentioned in issue team#70

    Toggle commit list
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment