From 8c4bb21050e2b050404275736280375daed2c8c4 Mon Sep 17 00:00:00 2001 From: Pierre-Antoine Rault Date: Wed, 21 Feb 2018 03:57:27 +0100 Subject: [PATCH] Add to onboard design contributors. --- Contribute-to-design.md | 166 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 Contribute-to-design.md diff --git a/Contribute-to-design.md b/Contribute-to-design.md new file mode 100644 index 0000000..f0676ec --- /dev/null +++ b/Contribute-to-design.md @@ -0,0 +1,166 @@ + + +## Contribute to PeerTube's design + +Thank you for your interest in contributing to PeerTube's design. This guide details how +to contribute in a way that is efficient for everyone. + +--- + +# Contribution guidelines + + + + + + +- [Onboarding :strawberry:](#onboarding-strawberry) + - [Software](#software) + - [Sketch](#sketch) + - [Adobe XD](#adobe-xd) +- [Organization](#organization) + - [Naming](#naming) + - [Files and folders](#files-and-folders) + - [Pages and artboards](#pages-and-artboards) + - [Major design proposals :bulb:](#major-design-proposals-bulb) +- [Git](#git) + - [Commits](#commits) + - [Large Files Storage](#large-files-storage) + + + +## Onboarding :strawberry: + +Everyone can contribute to PeerTube. 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. + +For all kinds of changes: + +1. Think of using pen & paper. Hi-end software isn't the goal. Design is. +1. [Fork this project][fork-link] to your personal namespace. +1. Make your changes while following the [naming](#naming) guidelines. +1. Replace `PeerTube-elements.sketch` in your fork with the changed version. Make sure you select the branch you created before. +1. Create a merge/pull request from your fork, selecting the appropriate source branch and this project's `develop` branch as the target. + - 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. + - Mention _only one_ of the maintainers to review. + - It's normal to have merge conflicts because we're dealing with binary files, please ignore. + - The merge request will ultimately be closed as the changes need to be merged manually, instead of using Git. + - please use the [PR template](https://gist.github.com/rigelk/3350ba0670a9b7fab9a3df08a1de6367). +1. High-five yourself and go brew some coffee while you wait for the review. Thanks! :raised_hands: + +### Software + +Again, think of using [paper & pencil first](http://alistapart.com/article/paperprototyping). + +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. + +Here are some software suggestions: + +#### Sketch + +Some pointers to open files from [Sketch](https://www.sketchapp.com/): + +- [Sketch-react](https://zjuasmn.github.io/sketch-react/): Web app that supports multiple pages. Admits uploading files and referencing by URL. +- [Sketch Web Viewer](https://animaapp.github.io/sketch-web-viewer/): Web app that supports uploaded files. +- [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. +- [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. + +We recommend installing the following Sketch plugins to improve your design +workflow. Don’t forget to read the documentation of each plugin to use them +properly. If you’d like to recommend a plugin, please [create an issue](https://PeerTube.com/PeerTube-org/PeerTube-design/issues/new). + +- [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. +- [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. + +#### Adobe XD + +Some pointers to open files from [Adobe XD](https://www.adobe.com/fr/products/xd.html). + +## Organization + +### Naming + +Follow these guidelines when naming files and folders, as well as +layers and styles in Sketch: +- Adhere to [BEM naming convention](http://getbem.com/naming/): `block-name__element-name--modifier-name` +- Readability above truncation: `background` instead of `bg` +- `lowercase` everywhere +- Separate words with dashes, `no-spaces` + +### Files and folders + +``` +- [group-label]/ (e.g. platform) + - [subject-labels]/ (e.g. settings) + - projecthandle#issueID-title.sketch (e.g. ce#1337-awesome-design.sketch) + - [projecthandle#issue-ID-title]/ + - projecthandle#issueID-title--state-one.sketch + - projecthandle#issueID-title--state-two.sketch + - assets/ + - asset.svg +``` + +1. - The 1st-level folders are named after the [Group label)](https://PeerTube.com/PeerTube-org/PeerTube-ce/blob/master/CONTRIBUTING.md#team-labels-cicd-discussion-edge-platform-etc) (also called team label) assigned to the issue/merge request (the green one; except [UX](https://PeerTube.com/PeerTube-org/PeerTube-ce/issues?label_name=UX)) + - The 2nd-level folders are named after [subject labels](https://PeerTube.com/PeerTube-org/PeerTube-ce/blob/master/CONTRIBUTING.md#subject-labels-wiki-container-registry-ldap-api-etc) assigned to the issue/merge request (the blue ones). If there are multiple Subject labels assigned, the folder is named after all labels, in alphabetical order, separated by a dash (e.g. `settings-wiki`). + - Sketch files are named after their related issue/merge request: + - The basic naming pattern is: `projecthandle#issueID-title.sketch`: + - Starts with the project handle (found in the project URL). Use the compact versions `ce` or `ee` for the Community Edition and Enterprise Edition, respectively. All other projects should have their full project handle (e.g. `ux-research` for the [UX Research project](https://PeerTube.com/PeerTube-org/ux-research)) + - The project handle is followed by `#` for issues or `!` for merge requests (e.g. `#1337` or `!1337`) + - The rest of the name should be a “compact” version of the issue/merge request title + - For example, the Sketch file for the issue [#28481 Display time tracking totals on milestone page](https://PeerTube.com/PeerTube-org/PeerTube-ce/issues/28481) on the Community Edition (CE) issue tracker could be named `ce#28481-time-tracking-totals.sketch` + - The Git hook that automates adding issue/merge request numbers to commit messages depends on using this naming pattern, so please follow it so that everything is nicely referenced (see [how to install it](#commits)) + - If the work is related to multiple issues and/or merge requests, just duplicate the prefix and separate with a dash (e.g. `ce#1234-ee#5678-awesome-design.sketch`). In the Sketch file, each page can be named after an issue/merge request (see the [Sketch](#sketch-) section). + - If you have assets or other files related to the main Sketch file, consider creating an “umbrella” folder to keep everything together. The folder should be named after the issue/merge request, following the same pattern as described before (e.g. `ce#1234-awesome-design`). + - If you think the Sketch file is becoming too complex, consider breaking it down into separate files, suffixing the file names with a double dash modifier (e.g. `ce#1234-awesome-design--anonymous.sketch` and `ce#1234-awesome-design--logged-in.sketch`). Then, create an “umbrella” folder, as described in the previous point. Alternatively, you can organize the Sketch file internally to deal with this complexity (see the [Sketch](#sketch-) section). + +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). + +### Pages and artboards + +In terms of organization method, use the one that best suits you. However, if +you think the file is becoming too complex, consider organizing it with different +pages and/or artboards. For example, pages can be different issues and artboards can be +different states. Remember to follow the [naming guidelines](#naming). + +See the [Files and folders](#files-and-folders) section for naming and +organizing Sketch files. + +### Major design proposals :bulb: + +Anything significant enough/complex enough to require further explanation that what a git repository and an issue can do, should be put in shape. We know issue threads are not enough in these cases, so feel free to put in shape a fully-fledged proposal such as [rethinkscape](https://github.com/PIWEEK/rethinkscape/). + +## Git + +Git is hard: screwing up is easy, and figuring out how to fix your mistakes is +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. + +Begin by [learning git interactively](https://try.github.io/), or with a video. + +Here are some more links and tips to help you +along! :v: + +- Revert your changes to a file and make it as if you never touched it: `git checkout FILEPATH/FILE` +- If you already did a commit but want to uncommit those changes (before pushing): `git reset HEAD^` +- If you feel you screwed up some more, there is the infamous [Dang it git!](http://dangitgit.com/) site. + +Note that as design files are usually binary files, merge conflicts can easily happen. We do the file merging manually instead of resolving with Git. + +### Commits + +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: + +- Write a [good commit message](https://chris.beams.io/posts/git-commit/) +- Install the [Git hook][git-hooks] that automates adding issue/merge request IDs to commit messages: + - 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. + - 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`). + - It only works if you follow the naming pattern described in the [Files and folders](#files-and-folders) section. + - 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). + +### Large Files Storage + +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. + +However, you need to set it up. A tutorial can be found on [GitHub's site](https://git-lfs.github.com/). + +[fork-link]: https://github.com/Chocobozzz/PeerTube/#fork-destination-box +[framer]: https://framer.com +[git-hooks]: https://git-scm.com/docs/githooks -- 2.25.1