Skip to content
Snippets Groups Projects
Commit e6e11a19 authored by Pedro Moreira da Silva's avatar Pedro Moreira da Silva
Browse files

Re-organize README and contribution guidelines 

- Add process for naming folder and files with IDs
- Compile contribution guidelines into own file
- Re-organize README
- Generate table of contents with DocToc: https://github.com/thlorenz/doctoc
parent f50507ff
No related branches found
No related tags found
1 merge request!9Resolve "Add issues/MRs IDs to progress folders names"
Hide whitespace changes
Inline Side-by-side
CONTRIBUTING.md 0 → 100644
+ 205
− 0
View file @ e6e11a19
# Contribution guidelines
<!-- Table of contents generated with DocToc: https://github.com/thlorenz/doctoc -->
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
- [Contribute to GitLab](#contribute-to-gitlab)
- [For wider community contributors :strawberry:](#for-wider-community-contributors-strawberry)
- [For GitLabbers :fox:](#for-gitlabbers-fox)
- [Organization](#organization)
- [Naming](#naming)
- [Files and folders](#files-and-folders)
- [Sketch :large_orange_diamond:](#sketch-large_orange_diamond)
- [Commits](#commits)
- [Superpowers :stars:](#superpowers-stars)
- [Git](#git)
- [Code of conduct](#code-of-conduct)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
## Contribute to GitLab
Thank you for your interest in contributing to GitLab. This guide details how
to contribute to GitLab in a way that is efficient for everyone.
Before contributing, get started by following the steps in the [README](/README.md#getting-started)
## For wider community contributors :strawberry:
Everyone can contribute to GitLab. For the wider community members we have a
[special `community-contribution` folder][community-folder] inside of the
[`progress`][progress-folder] directory. This is where you can create and commit your own designs.
This gives you a consistent backup location, which can also be used by other
people to iterate upon your designs. To start, please follow these steps:
1. Fork this repository and `git clone` it locally
1. Create a new branch based off from the master with `git checkout -b your-branch-name`
1. In the [`community-contribution`][community-folder] folder, create your personal folder named after your GitLab.com username (e.g. `@john`)
1. In your personal folder, create folders and files according to our [organization guidelines](#organization)
1. Review the files you are about to commit (with `git status -sb`)
- Remember, you’re only allowed to add or change files in your folder
- If you’re having a hard time with this whole Git thing, read our [small help section](#git)
1. Commit your changes, following our [commit guidelines](#commits)
1. Push your changes and [create a merge request](https://gitlab.com/gitlab-org/gitlab-design/merge_requests/new) to merge your branch to `master`
1. In that new merge request, mention any of the [designers who manage this project](/README.md#contacts)
## For GitLabbers :fox:
If you’re working on your personal files:
1. In the [`progress`][progress-folder] folder, create your personal folder named after your first name in lowercase (e.g. `pedro`)
1. In your personal folder, create folders and files according to our [organization guidelines](#organization)
1. If you’re working with Sketch specs created with the [Sketch Measure Plugin][sketch-measure], [Framer prototypes][framer], or static HTML pages, please refer to the [Superpowers](#superpowers-stars) section
1. Review the files you are about to commit (with `git status -sb`)
- If you’re having a hard time with this whole Git thing, read our [small help section](#git)
1. Commit and push your changes, following our [commit guidelines](#commits)
If you’re working on files inside of the [`production`][production-folder] folder:
1. [Lock file(s)](http://docs.gitlab.com/ee/user/project/file_lock.html)
1. Pull latest changes from the repository
1. Add your changes
1. Commit and push your changes, following our [commit guidelines](#commits)
1. [Unlock file(s)](http://docs.gitlab.com/ee/user/project/file_lock.html)
## Organization
### Naming
These naming guidelines should be applied to folder and file names, as well as
layers and styles inside of Sketch files.
- 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
```
- archive/
- hosted/
- [first-name]/
- [folders]/
- production/
- progress/
- community-contribution/
- [@gitlab.com-username]/ (e.g. @john)
- [team-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
- [gitlabber-first-name]/ (e.g. pedro)
- [team-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. [`archive/`](https://gitlab.com/gitlab-org/gitlab-design/tree/master/archive): Contains all old design files and resources, including those made with [Antetype](http://www.antetype.com/). Old Antetype design files can still be valuable if so see: [Converting Antetype files for use with Sketch](https://gitlab.com/gitlab-org/gitlab-ce/issues/19864)
1. [`hosted/`][hosted-folder]: Contains deliverables that are hosted online and are publicly accessible. Be very careful changing the structure of this folder as it might break external links. For more information, refer to the [Superpowers](#superpowers-stars) section.
1. [`progress/`][progress-folder]: Contains personal work-in-progress files. It’s assumed that [everything has a related issue][everything-starts-with-an-issue].
- Personal folders are organized around our [workflow labels](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md#workflow-labels)
- The 1st-level folders are named after the [Team label](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md#team-labels-ci-discussion-edge-platform-etc) assigned to the issue/merge request (the green one; except [UX](https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name=UX))
- The 2nd-level folders are named after [subject labels](https://gitlab.com/gitlab-org/gitlab-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 prefixed with the project handle (`ce` for Community Edition and `ee` for Enterprise Edition) and issue ID, separated by `#`. The rest of the name should be a “compact” version of the issue title. For example, the Sketch file for the issue [#28481 Display time tracking totals on milestone page](https://gitlab.com/gitlab-org/gitlab-ce/issues/28481) on the GitLab Community Edition (CE) issue tracker could be named `ce#28481-time-tracking-totals.sketch`.
- If the work is related to multiple issues, 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 (see the [Sketch](#sketch-large_orange_diamond) 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, 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-large_orange_diamond) section).
- For more information, refer to the [wider community contributors](#for-wider-community-contributors-strawberry) section or [GitLabbers](#for-gitlabbers-fox) section
## Sketch :large_orange_diamond:
- Use the [Symbol Resizing](https://blog.sketchapp.com/sketch-39-brings-symbol-resizing-and-cloud-beta-a74d3aa0611a#.rcu9qt4er) feature when creating symbols
- Add hidden *full red* (`#FF0000`) blocks for important paddings and margins.
- If you think the file is becoming too complex, consider organizing it with different pages and/or artboards. Use the organization method that best suits you. Pages can be different issues and artboards can be different states, for example. Remember to follow the [naming guidelines](#naming).
## Commits
- Be a good contributor and write a [good commit message](https://chris.beams.io/posts/git-commit/)
- If the changes you’re committing are related to an issue or merge request ([which they should be][everything-starts-with-an-issue]):
- In the commit message body, reference the project handle (`ce` for Community Edition and `ee` for Enterprise Edition) and issue/merge request ID (e.g. `gitlab-ce#1337` or `ux-research!1337`)
- If related to multiple issues or merge requests, put each reference on their own line
- These references create a commit note in the issue/merge request, making it easy for other people to contribute and fork the design (especially important if someone is out-of-office)
## Superpowers :stars:
Some deliverables (Sketch specs created with the [Sketch Measure Plugin][sketch-measure],
[Framer prototypes][framer], and static HTML pages) can be
automatically hosted online for you and are publicly accessible for quick and
easy design handoffs. You can [thank us later](https://about.gitlab.com/handbook/communication/#say-thanks).
To use these awesome _superpowers_:
1. Create a folder with your first name in the [`hosted` directory][hosted-folder] in lowercase (e.g. `john`). This way we can re-organize the repository without breaking any external links
1. Place your deliverable folder inside of your personal `hosted` directory
- Sketch specs created with the [Sketch Measure Plugin][sketch-measure]: append `-spec-previews` to the name of the export folder
- Framer prototypes: if you intend to share them, just move the `*.framer` folder to your personal `hosted` directory
- Static HTML pages: append `-html-previews` to the name of the folder and name the main page `index.html`
1. Commit and push your changes to GitLab
1. View your [commit’s pipeline on GitLab](https://gitlab.com/gitlab-org/gitlab-design/pipelines) and wait for it to pass
1. [Browse our index of hosted prototypes and specs][design-pages]
- Search by the name of your folder using <kbd>CMD/CTRL + F</kbd>
1. Share and rejoice! :open_hands:
## Git
As design files are usually binary files, merge conflicts can easily happen.
We do the file merging manually instead of resolving with Git.
Git is hard: screwing up is easy, and figuring out how to fix your mistakes is
sometimes almost impossible. Here are some links and tips to help you
along! :hugging:
- 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^`
- [Learn git interactively for free on codeschool](https://www.codeschool.com/learn/git)
- [Oh shit, git!](http://ohshitgit.com/)
## Code of conduct
As contributors and maintainers of this project, we pledge to respect all
people who contribute through reporting issues, posting feature requests,
updating documentation, submitting pull requests or patches, and other
activities.
We are committed to making participation in this project a harassment-free
experience for everyone, regardless of level of experience, gender, gender
identity and expression, sexual orientation, disability, personal appearance,
body size, race, ethnicity, age, or religion.
Examples of unacceptable behavior by participants include the use of sexual
language or imagery, derogatory comments or personal attacks, trolling, public
or private harassment, insults, or other unprofessional conduct.
Project maintainers have the right and responsibility to remove, edit, or
reject comments, commits, code, wiki edits, issues, and other contributions
that are not aligned to this Code of Conduct. Project maintainers who do not
follow the Code of Conduct may be removed from the project team.
This code of conduct applies both within project spaces and in public spaces
when an individual is representing the project or its community.
Instances of abusive, harassing, or otherwise unacceptable behavior can be
reported by emailing `contact@gitlab.com`.
This Code of Conduct is adapted from the [Contributor Covenant][contributor-covenant],
version 1.1.0, available at [http://contributor-covenant.org/version/1/1/0/](http://contributor-covenant.org/version/1/1/0/).
[community-folder]: https://gitlab.com/gitlab-org/gitlab-design/tree/master/progress/community-contribution
[hosted-folder]: https://gitlab.com/gitlab-org/gitlab-design/tree/master/hosted
[production-folder]: https://gitlab.com/gitlab-org/gitlab-design/tree/master/production
[progress-folder]: https://gitlab.com/gitlab-org/gitlab-design/tree/master/progress
[sketch-measure]: https://github.com/utom/sketch-measure
[design-pages]: https://gitlab-org.gitlab.io/gitlab-design
[framer]: https://framer.com
[everything-starts-with-an-issue]: https://about.gitlab.com/handbook/communication/#everything-starts-with-an-issue
README.md
+ 59
− 137
View file @ e6e11a19
# [GitLab Design Kit](https://gitlab-org.gitlab.io/gitlab-design)
# GitLab Design
 
Contains all resources and information UX Designers need.
Git LFS is enabled for this repository. It tracks the following files: `.atype`, `.sketch`, `.psd`, `.zip`, `.jpg`, `.png`, `.pdf`.
Please do the following before committing to this repository:
- `git lfs install`
If you use an application git client instead of the command-line please look in the docs/manual of your app how to activate git LFS!
__An archive of this repository, containing all original commit prior to the change to use git LFS at 08-07-2017 can be found [here](https://gitlab.com/gitlab-org/gitlab-design-archive)!__
:information_source: **This project is primarily used by [GitLab’s UX team][ux-handbook]
to host design files and hand them off for implementation. To get help or
raise a bug/feature proposal for GitLab, please create an issue on the
[GitLab Community Edition issue tracker](https://gitlab.com/gitlab-org/gitlab-ce/issues)
or [GitLab Enterprise Edition issue tracker](https://gitlab.com/gitlab-org/gitlab-ee/issues),
or see [Getting help for GitLab](https://about.gitlab.com/getting-help/) on our
website for the many options to get help.**
 
![gitlab-cover-image](https://gitlab.com/gitlab-org/gitlab-design/raw/master/gitlab-cover-image.jpg)
 
## Repository SUPERPOWERS :stars:
*Please put all exported folders in the `hosted` directory. That way you can shuffle the rest of your repository around without breaking links!*
- __Semi automatic Sketch spec previews with Continuous Integration__
*Whenever you create a spec preview folder with the [Sketch Measure Plugin](https://github.com/utom/sketch-measure), append `spec-previews` to the name of the generated directory and it will be visible by an URL. Search in [https://gitlab-org.gitlab.io/gitlab-design](https://gitlab-org.gitlab.io/gitlab-design)*
- __Automatic live Framer prototypes with Continuous Integration__
*Whenever you save a [Framer](https://framerjs.com) prototype in this repository and commit push it to GitLab, it will automatically be hosted in the same way as the spec previews superpower. See them live at [https://gitlab-org.gitlab.io/gitlab-design](https://gitlab-org.gitlab.io/gitlab-design)*
- __Standalone Live Html Previews__
*By using the wget command: `wget -kN --html-extension URL` or `wget -E -p -k URL` you can create a standalone working HTML page of the GitLab view you want. Just change the name of the file to index.html and append `html-previews` to the name of the directory it will be inside of. Good luck! (No guarantees with this one!)*
### Activating them!
1. Have a Mac with [Sketch](https://www.sketchapp.com/) installed in the /Applications folder
1. Install [Sketch Measure Plugin](https://github.com/utom/sketch-measure) with the Sketch Toolbox
1. Read on :)
## Repository Organization
- archive/
- oldfiles/
- production/
- svg/
- resources/
- progress/
- community-contribution/
- @gitlabusername/
- projects/
- project.sketch
- GitLab-designername/
- application-section/
- project.sketch
## Commit Workflow (includes Community Contribution!)
As design files are mostly binary files, merge conflicts can easily get stuck in conflicts. We will do the file merging manually instead of git.
### GitLab Designer Personal Folders
1. In the `progress` directory, create your own folder
1. In your own folder, create a subfolder for each issue/project you are working on
1. Commit & Push changes
### Community Contribution :strawberry:
- **[Browse prototypes and specs :arrow_upper_right:][design-pages]**
 
Every designer can contribute to GitLab. For GitLab community members we have a [special folder](https://gitlab.com/gitlab-org/gitlab-design/tree/master/progress/community-contribution) in the `progress` directory where you can create and commit your own designs. So you have a consistent backup, which can also be used by other designers to iterate upon! Follow the following steps to contribute.
<!-- Table of contents generated with DocToc: https://github.com/thlorenz/doctoc -->
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 
1. Fork this repository and `git clone` it locally.
1. Create a new branch based off from the master with `git checkout -b branchname`
1. In the `community-contribution` directory, create your own folder based on your GitLab username following [the example](https://gitlab.com/gitlab-org/gitlab-design/tree/master/progress/community-contribution/@gitlabusername).
1. In your own folder, create a subfolder for each issue/project you are working on.
1. Review the files you are about to commit (with `git status -sb`), as __only files in your folder are allowed to be added or changed__! If you have a hard time with this read through our [small section on Git](#oh-my-git)
1. Commit your changes with a [good commit message](https://chris.beams.io/posts/git-commit/), including the project path and issue ID in the commit message body (e.g. `gitlab-ce#1337`). If the commit relates to multiple issues, put them on their own line. This creates a commit note in the issue, making it easy for other people to contribute and fork the design (especially important if someone is out-of-office).
1. Push your changes, create a merge request, and mention any [designer who manages this project](#project-managers).
 
### Production Folders
- [About](#about)
- [Goals](#goals)
- [Getting started](#getting-started)
- [Contributing](#contributing)
- [Contacts](#contacts)
- [Links](#links)
- [License](#license)
 
1. [Lock file](http://docs.gitlab.com/ee/user/project/file_lock.html)
1. Pull changes
1. Add our changes to the file
1. Commit & Push changes
1. [Unlock](http://docs.gitlab.com/ee/user/project/file_lock.html) file
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
 
## Naming Convention
Please see this [issue #19](https://gitlab.com/gitlab-org/gitlab-design/issues/19) for conversation on this topic
## About
 
### Everywhere
**GitLab’s open source design library, prototypes and work-in-progress files.**
 
- Readability above truncation, so: `background` instead of `bg`
- `lowercase` __everywhere__
- separate words with hyphens, _no-spaces-everywhere__
This project is primarily used by [GitLab’s UX team][ux-handbook] to host design
files and hand them off for implementation. To learn about the best
practices to manage this project, including the repository’s organization,
check out the [contribution guidelines](/CONTRIBUTING.md). For more information
about the UX team, check out the [Links](#links) section.
 
### Files & Folders
### Goals
 
- for each issue create subfolders for issues
- Jumpstart design work by using the design library and previous work
- Enable frequent, stable, and consistent contributions
- Make GitLab’s design open, transparent, and open source
- Facilitate design handoffs and design–development communication design handoffs.
 
### Layers & Groups (inside Sketch)
## Getting started
 
- Try to adhere to [BEM naming convention](http://getbem.com/naming/) like so: block-element__modifier
**If you’re a GitLab Inc. engineer**: you shouldn’t have to clone this project,
ever. Instead, ask the UX designer for the specs of the designs you’re working with.
 
Example:
**If you want to browse and contribute**:
 
- `navigation-1__project`
1. Have a Mac with [Sketch](https://www.sketchapp.com/) installed, as most of the repository is made of Sketch files
1. Install and enable [Git Large File System (LFS)](https://about.gitlab.com/2017/01/30/getting-started-with-git-lfs-tutorial/):
1. Install with [Homebrew](https://github.com/Homebrew/brew) via `brew install git-lfs` or [MacPorts](https://www.macports.org/) via `port install git-lfs`
1. Enable with `git lfs install`
- If you use a [Git GUI client](https://git-scm.com/download/gui/mac) (e.g. Tower) instead of the command line, look in the docs/manual of your app to see how you can install/enable Git LFS
1. Refer to the [contribution guidelines](/CONTRIBUTING.md) before contributing
 
- if you need to add the modifier, you can: `navigation-1__project--issues`
Git LFS currently tracks the following file extensions on the repository:
`.atype`, `.sketch`, `.psd`, `.zip`, `.jpg`, `.png`, and `.pdf`.
An [archive of the repository before using Git LFS](https://gitlab.com/gitlab-org/gitlab-design-archive)
was created on July 8, 2017.
 
## Sketch Management
## Contributing
 
- Please try to use the [Symbol Resizing](https://blog.sketchapp.com/sketch-39-brings-symbol-resizing-and-cloud-beta-a74d3aa0611a#.rcu9qt4er) feature, when creating symbols
- Add hidden *full red* (#FF0000) blocks, for important paddings and margins.
GitLab is an open source project and we are very happy to accept community
contributions. Please refer to [CONTRIBUTING.md](/CONTRIBUTING.md) for details.
 
## Delivery
## Contacts
 
All designs mockups and details are delivered in the issue that describes the feature/problem/etc. So there is one place to look for everything related to it.
## Designer & Developer Communication
> Designers and developers often have different priorities, even though everyone is working toward one common goal: a fantastic, delightful, functional product. At Google, we're always working on ways to bridge this gap through unified spec formats and tools, so that intricate details are never lost in translation and things get done the way they're intended the first time - [Designer & Developer Communication Google IO 2016](https://www.youtube.com/watch?v=ZFyK1J5NrVk)
Spec previews can be generated with the one of the [SUPERPOWERS](#repository-superpowers-)!
When additional detail is needed, developers will ask for this. Take inspiration out of the link above if needed.
## Oh My Git
Git is hard: screwing up is easy, and figuring out how to fix your mistakes is sometimes almost impossible. Here are some links and tips to help you along!
### Git Tips
__Delete your changes on a file and make it as if you never touched it! (before commited anything)__
- `git checkout FILEPATH/FILE`
__If you did already 1 commit, but want to uncommit those changes__
- `git reset HEAD^`
### Git Links
- [Learn git interactively for free on codeschool](https://www.codeschool.com/learn/git)
- [Oh shit, git!](http://ohshitgit.com/)
## Project maintainers
See the [members section](https://gitlab.com/gitlab-org/gitlab-design/settings/members?sort=access_level_desc) of this project and search for "UX" on the [team section](https://about.gitlab.com/team) on our website.
## Archive
The archive directory contains all old design files and resources, including those made with [Antetype](http://www.antetype.com/).
Old Antetype design files can still be valuable, if so see: [Converting antetype files for use with sketch](https://gitlab.com/gitlab-org/gitlab-ce/issues/19864)
Search for `UX` on the [team page](https://about.gitlab.com/team) on our website.
 
## Links
- [UX Guide](https://docs.gitlab.com/ce/development/ux_guide/)
- [UI Development Kit](https://gitlab.com/help/ui)
- [UX Designer Onboarding Page](https://about.gitlab.com/handbook/uxdesigner-onboarding/)
- [UX Handbook][ux-handbook]
- [UX Designer Onboarding](https://about.gitlab.com/handbook/uxdesigner-onboarding/)
- [GitLab Dribbble](https://dribbble.com/gitlab)
 
## Design goals
- Get the user started with all already existing materials
- Try to kickstart design work while avoiding time lost on creating the duplicate content
- Let designers contribute in a stable and consistent manner
## License
 
The GitLab Design Kit is distributed under the MIT license,
see the [LICENSE](https://gitlab.com/gitlab-org/gitlab-design/blob/master/LICENSE) file.
The GitLab Design Kit is distributed under the MIT license, see the [LICENSE](/LICENSE)
for details.
[design-pages]: https://gitlab-org.gitlab.io/gitlab-design
[ux-handbook]: https://about.gitlab.com/handbook/ux/
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