Contribute-to-design.md

   1 <!-- This guide is heavily inspired by GitLab's own contributing guide for its design team. Kudos to them! -->
   2
   3 Thank you for your interest in contributing to PeerTube's design. Our team is building a software, but we don't forget its core concept still is to interact with people. Here's how you can help them better get along.
   4
   5 ---
   6
   7 # Contribution guidelines
   8
   9 <!-- Table of contents generated with DocToc: https://github.com/thlorenz/doctoc -->
  10 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
  11 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
  12
  13
  14 - [Onboarding :strawberry:](#onboarding-strawberry)
  15   - [Open Source Design](#open-source-design)
  16   - [Suggested workflow](#suggested-workflow)
  17   - [Suggested Software](#suggested-software)
  18     - [Sketch](#sketch)
  19     - [Adobe XD](#adobe-xd)
  20 - [Organization](#organization)
  21   - [Naming](#naming)
  22   - [Files and folders](#files-and-folders)
  23   - [Pages and artboards](#pages-and-artboards)
  24 - [Git](#git)
  25   - [Commits](#commits)
  26   - [Large Files Storage](#large-files-storage)
  27
  28 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
  29
  30 ## Onboarding :strawberry:
  31
  32 Everyone can contribute to PeerTube's design. Anyone who influences what the design becomes is the designer. This includes developers, PMs, even corporate legal. All are the designers.<sup>[1](https://twitter.com/jmspool/status/836955987860914176)</sup>
  33
  34 The project is still low on resources and no dedicated design team has been established, nor a dedicated design repository − yet. We are trying to get you to speed nonetheless, and make communication between design-literate and code-literate people as easy as possible.
  35
  36 ### Open Source Design
  37
  38 We care about [Open Source Design](http://opensourcedesign.net/goals/), and Open Design in general. Making the design process open is an important thing for us, as interfaces too can greatly impact the resulting software, in bad or good.
  39
  40 It implies putting your files in the open and iterating to modify it with others until consensus. More specifically, it means dividing a given design problem in manageable parts, and track them [in public](issue-link) for us to help :smiley:.
  41
  42 You might want to read some more here, although these are just hints:
  43 - http://opendesignkit.org/process/
  44
  45 ### Suggested workflow
  46
  47 1. See what you think about is being tackled by others on the [issue tracker](issue-link)
  48 1. Think of using pen & paper. High-end software isn't the goal. Design is.
  49 <!-- 1. [Fork this project][fork-link] to your personal namespace. Or don't: it's just a suggested skeleton project to help you get started and structure your proposal. -->
  50 1. Create a repository from your fork.
  51    - Be very descriptive of the changes you've made. The reviewer will have to manually merge them, which means they have to be aware of even the smallest changes as they could be easy to miss.
  52 1. Create an issue on [PeerTube's repository](issue-link).
  53    - Please use this [issue template](https://gist.github.com/rigelk/3350ba0670a9b7fab9a3df08a1de6367).
  54    - Mention _only one_ of the maintainers to review.
  55    - The issue will ultimately be edited/closed as the changes need to be converted to integration/code tasks.
  56 1. High-five yourself and go brew some :coffee: while you wait for the review(s). Thanks! :raised_hands:
  57
  58 ### Suggested Software
  59
  60 Again, think of using [paper & pencil first](http://alistapart.com/article/paperprototyping).
  61
  62 We recommend first and foremost open source software such as [Inkscape](https://inkscape.org/en/) or [Pencil](http://pencil.evolus.vn/) (a [complete list](http://opensourcedesign.net/resources/#design-tools)), but at the same time we know most of them are behind popular software for web design workflows. You can use any design software that's available to you. Just make sure to include editable exports (SVG, PDF, EPS) along with your source files.
  63
  64 #### Gravit Designer
  65
  66 Multiplatform and can be used online too ([freeware](https://discuss.gravit.io/t/how-does-gravit-make-money/3002/2)).
  67
  68 #### Sketch
  69
  70 Some pointers to open files from [Sketch](https://www.sketchapp.com/):
  71
  72 - [Sketch-react](https://zjuasmn.github.io/sketch-react/): Web app that supports multiple pages. Admits uploading files and referencing by URL.
  73 - [Sketch Web Viewer](https://animaapp.github.io/sketch-web-viewer/): Web app that supports uploaded files.
  74 - [Figma](https://www.figma.com/): Powerful tool for UX and UI design. It has a web interface as well as desktop apps (internet connection required). It’s free for individuals.
  75 - [Photopea](https://www.photopea.com/): Free web editor for Sketch, Photoshop and Gimp files. The only editable export format is PSD, which may not be fully compatible for Sketch import.
  76
  77 We recommend installing the following Sketch plugins to improve your design
  78 workflow. Don’t forget to read the documentation of each plugin to use them
  79 properly. If you’d like to recommend a plugin, please [create an issue](https://PeerTube.com/PeerTube-org/PeerTube-design/issues/new).
  80
  81 - [Relabel Button](https://github.com/kenmoore/sketch-relabel-button): Prompts for a button’s new label, applies the text, resizes the button background, and repositions any other interior elements while maintaining the existing padding. It’s essentially awesome voodoo magic.
  82 - [Git Plugin](https://mathieudutour.github.io/git-sketch-plugin/): A Git client built right into Sketch. The plugin really improves the review process by exporting an image for every part of the design.
  83
  84 #### Adobe XD
  85
  86 Some pointers to open files from [Adobe XD](https://www.adobe.com/fr/products/xd.html).
  87
  88 ## Organization
  89
  90 ### Naming
  91
  92 Follow these guidelines when naming files and folders, as well as
  93 layers and styles in your source files:
  94 - Adhere to [BEM naming convention](http://getbem.com/naming/): `block-name__element-name--modifier-name`
  95 - Readability above truncation: `background` instead of `bg`
  96 - `lowercase` everywhere
  97 - Separate words with dashes, `no-spaces`
  98
  99 ### Files and folders
 100
 101 ```
 102 - [group-label]/ (e.g. platform)
 103   - [subject-labels]/ (e.g. settings)
 104     - projecthandle#issueID-title.sketch (e.g. ce#1337-awesome-design.sketch)
 105     - [projecthandle#issue-ID-title]/
 106       - projecthandle#issueID-title--state-one.sketch
 107       - projecthandle#issueID-title--state-two.sketch
 108         - assets/
 109           - asset.svg
 110 ```
 111
 112 In any case, if the project becomes too complex (i.e. for a complete redesign proposal, please refer to the [design proposals section](#major-design-proposals).
 113
 114 ### Pages and artboards
 115
 116 In terms of organization method, use the one that best suits you. However, if
 117 you think the file is becoming too complex, consider organizing it with different
 118 pages and/or artboards. For example, pages can be different issues and artboards can be
 119 different states. Remember to follow the [naming guidelines](#naming).
 120
 121 See the [Files and folders](#files-and-folders) section for naming and
 122 organizing Sketch files.
 123
 124 ## Git
 125
 126 Git is hard: screwing up is easy, and figuring out how to fix your mistakes is
 127 sometimes almost impossible. Yet that's one of the best tool to deal with heterogeneous groups of people (you!) coming from all over the world. It brings structure to chaos.
 128
 129 Begin by [learning git interactively](https://try.github.io/), or with [a video](https://git-scm.com/videos). There is also that [dead simple site explaining it](http://rogerdudler.github.io/git-guide/). Or the verbose [official documentation of Git](https://git-scm.com/doc). Tons of ways, really.
 130
 131 Here are some more links and tips to help you
 132 along! :v:
 133
 134 - Revert your changes to a file and make it as if you never touched it: `git checkout FILEPATH/FILE`
 135 - If you already did a commit but want to uncommit those changes (before pushing): `git reset HEAD^`
 136 - If you feel you screwed up some more, there is the infamous [Dang it git!](http://dangitgit.com/) site, and don't be afraid to ask us.
 137
 138 Don't forget the section about `git-lfs`. Large files as graphics sources slow down Git, and need that special plugin to be dealt with.
 139
 140 ### Commits
 141
 142 Commiting changes is the action to bundle the changes you've made in a set that can be shared with others. Of course some rules apply to that step, and good practices too that can help you do more with commits:
 143
 144 - Write a [good commit message](https://chris.beams.io/posts/git-commit/)
 145 - Install the [Git hook][git-hooks] that automates adding issue/merge request IDs to commit messages:
 146    - At the root of the repository, run `ln -s ../../hooks/prepare-commit-msg .git/hooks/prepare-commit-msg`. This will keep your local Git hook up-to-date.
 147    - Once installed, every time you commit, the hook will add the issues and merge requests IDs found on the staged files (and their folders) to the commit message body (e.g. `PeerTube-webui#1337` or `ux-research!1337`).
 148    - It only works if you follow the naming pattern described in the [Files and folders](#files-and-folders) section.
 149    - These references automatically create a commit note in the corresponding issue/merge request, making it easy for other people to contribute and fork the design (especially important if someone is out-of-office).
 150
 151 ### Large Files Storage
 152
 153 Sketch files or PSDs can be huge, and well above what Git is made for (files way under 100MB). But fear not, Git Large File Storage (LFS) replaces large files such as audio samples, videos, datasets, and graphics with text pointers inside Git, while storing the file contents on a remote server.
 154
 155 However, you need to set it up. A tutorial can be found on [GitHub's site](https://git-lfs.github.com/).
 156
 157 [fork-link]: https://github.com/Chocobozzz/PeerTube/#fork-destination-box
 158 [issue-link]: https://github.com/Chocobozzz/PeerTube/labels/ui
 159 [framer]: https://framer.com
 160 [git-hooks]: https://git-scm.com/docs/githooks