Team Handbook

Welcome to the GitLab Handbook

The GitLab team handbook is the central repository for how we run the company. As part of our dedication to being as open and transparent as possible, the handbook is open to the world, and we welcome feedback. Please make a merge request to suggest improvements or add clarifications. Please use issues to ask questions.


Other Main Pages in Handbook


This page


Values

We value results, transparency, sharing, freedom, efficiency, frugality, collaboration, directness, kindness, diversity, boring solutions, and quirkiness:

  1. Results: We care about what you achieve; the code you shipped, the user you made happy, and the team member you helped. Do not compete by proclaiming how many hours you worked yesterday because we don't want someone who took the afternoon off to feel like they did something wrong. Instead celebrate the achievements of yourself and your teammates. We want people to have the desire to ship.
  2. Transparency: Be open about as many things as possible. By making information public we can reduce the threshold to contribution and make collaboration easier. An example is the public repository of this website that also contains this company handbook. Everything we do is public by default, for example the GitLab CE and GitLab EE issue trackers, but also marketing and infrastructure. Transparency creates awareness for GitLab, allows us to recruit people that care about our culture, it gets us more and faster feedback from people outside the company, and makes it easier collaborate with them. There are exceptions, material that is not public by default is documented in the general guidelines. On a personal level you should tell it like it is instead of putting up a poker face. Don't be afraid to admit you made a mistake or were wrong. When something went wrong it is a great opportunity to say 'what’s the kaizen moment here' and find a better way without hurt feelings.
  3. Sharing: We care about giving great software, documentation, examples, lessons, and processes to the world. An example is the MIT licensed GitLab CE. We believe that open source creates more value than it captures. We are grateful to our customers, users, partners, investors, and the open source ecosystem.
  4. Freedom: You should have clear objectives and the freedom to work on them as you see fit. Any instructions are open to discussion. You don't have to defend how you spend your day. We trust team members to do the right thing instead of having rigid rules.
  5. Efficiency: We care about working on the right things, not doing more than needed, and not duplicating work. This enables us to achieve more progress with fewer people and makes our work more fulfilling. We think of how we can make the company better instead of being territorial or defensive.
  6. Frugality: Amazon states it best with: "Accomplish more with less. Constraints breed resourcefulness, self-sufficiency and invention. There are no extra points for growing headcount, budget size or fixed expense."
  7. Collaboration: Helping others is a priority, even when it is not related to the goals that you are trying to achieve. You are expected to ask others for help and advice. Anyone can chime in on any subject, including people who don't work at GitLab. The person who has to do the work decides how to do it but you should always take the suggestions seriously and try to respond and explain.
  8. Directness: We try to channel our inner Ben Horowitz by being both straightforward and kind, an uncommon cocktail of no-bullshit and no-asshole. Although the feedback is always about your work and not your person it will not be easy to receive it.
  9. Kindness: We don't want jerks in our team. Some companies say Evaluate People Accurately, Not "Kindly". We're all for accurate assessment but we think it must be done in a kind way. Give as much positive feedback as you can and do it in a public way. Give negative feedback in the smallest setting possible, one-on-one video calls are preferred. Clearly make negative feedback about the work itself, not the person. When giving feedback always provide at least one clear and recent example. If a person is going through a hard time in their personal life, then take that into account. An example of giving positive feedback is our thanks chat channel.
  10. Diversity: The community consists of people from all over the world, with different backgrounds and opinions. We hire globally and encourage hiring in a diverse set of countries. We work to make everyone feel welcome and to increase the participation of underrepresented minorities and nationalities in our community and company. An example is our sponsorship of diversity events.
  11. Boring solutions: Use the most simple and boring solution for a problem. You can always make it more complex later if that is needed. The speed of innovation for our organization and product is constrained by the total complexity we have added so far, so every little reduction in complexity helps. Don't pick an interesting technology just to make your work more fun, using code that is popular will ensure many bugs are already solved and its familiarity makes it easier for others to contribute.
  12. Quirkiness: Unexpected and unconventional things make life more interesting. Celebrate and encourage quirky gifts, habits, behavior, and points of view. An example is our team call where we spend most of our time talking about what we did in our private lives, from fire-throwing to knitting. Open source is a great way to interact with interesting people. We try to hire people who think work is a great way to express themselves.

General Guidelines

  1. Working at GitLab Inc. is cooperating with the most talented people you've ever worked with, being the most productive you'll ever be, and creating software that is helping the most people you've ever reached.
  2. We recognize that inspiration is perishable, so if you’re enthusiastic about something that generates great results in relatively little time feel free to work on that.
  3. Do what is right for our customers and the rest of the GitLab community, do what is best over the long term, don't be evil.
  4. We create simple software to accomplish complex collaborative tasks.
  5. We use our own software to accomplish complex collaborative tasks.
  6. Do not make jokes or unfriendly remarks about race, ethnic origin, skin color, gender or sexual orientation.
  7. Use inclusive language. For example, prefer 'Hi everybody' or 'Hi people' to 'Hi guys'.
  8. Share problems you run into, ask for help, be forthcoming with information and speak up.
  9. Don't display surprise when people say they don't know something, as it is important that everyone feels comfortable saying "I don't know" and "I don't understand." (Inspired by Recurse)
  10. All our procedures and templates are stored in (mostly public) git repositories instead of Google/Word documents. This makes them easier to find and suggest changes to with the organization and shows our commitment to open collaboration outside the organization.
  11. Work out in the open, try to use public issue trackers and repositories when possible.
  12. Most things are public unless there is a reason not to, not public by default are: financial information, legal, job applications/compensation/feedback and partnerships with other companies.
  13. Share solutions you find and answers you receive with the whole community.
  14. If you make a mistake, don't worry, correct it and proactively let the affected party, your team, and the CEO know what happened, how you corrected it and how, if needed, you changed the process to prevent future mistakes.
  15. You can always refuse to deal with people who treat you badly and get out of situations that make you feel uncomfortable.
  16. Everyone can remind anyone in the company about these guidelines. If there is a disagreement about the interpretations, the discussion can be escalated to more people within the company without repercussions.
  17. If you are unhappy with anything (your duties, your colleague, your boss, your salary, your location, your computer) please let your boss, or the CEO, know as soon as you realize it. We want to solve problems while they are small.
  18. We want to have a great company so if you meet people that are better than yourself try to recruit them to join the company.
  19. Make a conscious effort to recognize the constraints of others within the team. For example, sales is hard because you are dependent on another organization, and Development is hard because you have to preserve the ability to quickly improve the product in the future.
  20. Our strategy is detailed on the Strategy page, please read it and contribute.
  21. For each action or comment, it helps to ask yourself (i) does this help the company achieve its strategic goals? (ii) is this in the company's interest, and finally, (iii) how can I contribute to this effort/issue in a constructive way?
  22. There is no need for consensus, make sure that you give people that might have good insights a chance to respond (by /cc'ing them) but make a call yourself because consensus doesn't scale.
  23. Everyone at the company cares about your output. Being away from the keyboard during the workday, doing private browsing or making personal phone calls is fine and encouraged.
  24. If you fix something for GitLab.com or one of our users make sure to make that the default (preferred) and radiate the information in the docs. We should run GitLab.com with the default settings and setup our users would also have.
  25. Everything is always in draft and subject to change, including this handbook. So do not delay documenting things and do not include draft in the titles of documents. Ensure everyone can read the current state, nothing will ever be finished.
  26. Explicitly note what next action you propose or expect and from whom.
  27. When you reply to a request please do so after you have completed the request or indicate when you plan to do it. In the latter case always send a second message when the request is complete.
  28. Respect the privacy of our users and your fellow team members. Secure our production data at all times. Only work with production data when this is needed to perform your job. Looking into production data for malicious reasons (for example LOVEINT or spying on direct messages of team members) is a fireable offense.
  29. Most guidelines in this handbook are meant to help and unless they state otherwise it is meant to help more than being an absolute rule. Don't be afraid to do something because you can't oversee all guidelines. Be gentle when reminding people about these guidelines, for example say: "It is not a problem, but next time please consider the following guideline from the handbook".

Handbook Usage

At GitLab our handbook is extensive and keeping it relevant is an important part of everyone's job. The reasons for having a handbook are:

  1. Reading is much faster than listening.
  2. Reading is async, you don't have to interrupt someone or wait for them to become available.
  3. Recruiting is easier if people can see what we stand for and how we operate.
  4. Retention is better if people know what they are getting into before they join.
  5. Onboarding is easier if you can find all relevant information spelled out.
  6. Teamwork is easier if you can read how other parts of the company work.
  7. Discussing changes is easier if you can read what the current process is.
  8. Communicating change is easier if you can just point to a diff.
  9. Everyone can contribute to it by proposing a change via a merge request.

Documenting things in the handbook takes more time initially and it requires thinking. But it saves time over a longer period and it is essential to scale and adapt our organization. It is not unlike writing tests for your software. Please follow these guidelines and remind others of them.

  1. If you need to discuss with a team member for help please realize that probably the majority of the community also doesn't know, be sure to document the answer to radiate this information to the whole community. After the question is answered discuss where it should be documented and who will do it. You can remind other people of this by asking 'who will document this'?
  2. When you discuss something in chat always try to link to a URL where relevant, for example the documentation you have a question about or the page that answered your question. You can remind other people of this by asking 'can you please link'?
  3. To change a guideline or process, suggest an edit in the form of a merge request. After it is merged you can talk about it during the team call if applicable. You can remind other people of this by asking 'can you please send a merge request for the handbook'?
  4. Communicate process changes by linking to the diff (a commit that shows the changes before and after). Do not change the process first, and then view the documentation as a lower priority task. Planning to do the documentation later inevitably leads to duplicate work communicating the change and to outdated documentation. You can remind other people of this by asking 'can you please update the handbook first?'.
  5. When communicating something always include a link to the relevant (and up to date) part of the handbook instead of including the text in the email/chat/etc. You can remind other people of this by asking 'can you please link to the relevant part of the handbook?'.
  6. If you copy content please remove it at the origin place and replace it with a link to the new content. Duplicate content leads to updating it in the wrong place, keep it DRY.

Many things can be documented in the handbook, but this will mostly be read by team members. If something can concern users of GitLab it should be documented in the GitLab documentation, the GitLab Development Kit (GDK), our CONTRIBUTING file or the PROCESS file.

Communication

We're a distributed, remote-only company where people work remote without missing out. For this, we use asynchronous communication and are as open as we can be by communicating through public issues, chat channels, and placing an emphasis on ensuring that conclusions of offline conversations are written down. These communication guidelines are meant to facilitate smooth communication in an ever-growing remote-only company. Please keep in mind that you represent GitLab and our culture, also on Social Media. When commenting on posts please keep in mind: "Don't argue but represent."

Internal Communication

  1. All written communication happens in English, even when sent one on one, because sometimes you need to forward an email or chat.
  2. Use asynchronous communication when possible (issues and email instead of chat), issues are preferred over email, email is preferred over chat, announcements happen on the team call agenda, and people should be able to do their work without getting interrupted by chat.
  3. It is very OK to ask as many questions as you have, but ask them so many people can answer them and many people see the answer (so use issues or public chat channels instead of private messages or one-on-one emails) and make sure you try to document the answers.
  4. If you mention something (a merge request, issue, commit, webpage, comment, etc.) please include a link to it.
  5. All company data should be shareable by default. Don't use a local text file but leave comments on an issue.

Email

  1. When using email, send one email per subject as multiple items in one email will cause delays (have to respond to everything) or misses (forgot one of the items).
  2. Always reply to emails, even when no action is needed. This lets the other person know that you received it. A thread is done when there is a single word reply, such as OK, thanks, or done.
  3. If you forward an email without other comments please add FYI (for your information) or FYA (for your action). If you forward an external request with FYA it doesn't mean that the company should do whatever is proposed, it just means the person who forwarded it will not follow up on the request themselves and expects you to do so instead.
  4. Email forwarding rules are specified in the shared "GitLab Email Forwarding" Google doc accessible to people in the company, if you want to be added or removed from an internal alias (e.g. sales@gitlab.com), change a rule, or add a forwarding email alias, please make a suggestion in the document.
  5. Emails are asynchronous, for example if your manager emails you on a weekend it is fine to reply during the workweek.
  6. If an email is or has become urgent feel free to ping people via chat referencing the subject of the email.

Chat

  1. If you use chat please use a public channel whenever possible, mention the person you want to reach if it is urgent. This ensures it is easy for other people to chime in, and easy to involve other people, if needed.
  2. In chat try to keep the use of keywords that mention the whole channel to a minimum. They should only be used for pings that are both urgent as well as important. By overusing channel mentions you make it harder to respond to personal mentions in a timely manner since people get pinged too frequently.
  3. If you agree in a chat to start a video call (typically by asking 'call?') the person that didn't leave the last comment starts the call. So either respond to the 'call?' request with a video link or say 'yes' and let the other person start it. Don't say 'yes' and start a call 5 seconds later since it is likely you'll both be creating a video call link at the same time.

Google Docs

  1. Work on website edits via commits to a merge request. Never use a Google doc for something non-confidential that is intended for the website.
  2. If you do need a Google Doc, then create the doc with your company Google Apps account. By default share Google docs with the whole company 'anyone at GitLab can find and access' with edit (preferred) or comment access for everyone. An easy way to do this, is to create your Google docs in a Shared Folder in Google Drive.
  3. When referring to a Google Doc in the handbook, refrain from providing the direct link. Instead, write the name of the Google Doc. In the past, giving the URL of a doc has led to inadvertent opening of sharing settings beyond what was intended, and it also helps prevent spam from people outside of GitLab who request access to the doc when they see the link.
  4. If you are having trouble finding a shared Google Doc, make sure you Search <your domain> in Google Drive.
  5. In our handbook, if you find yourself wondering whether it is better to provide a public link to a Google Doc vs. writing out the content on the website, use the following guideline: Is this document frequently adapted / customized? If yes, then provide a link, making sure that the document can be commented on by anyone with the link. For instance, this is how we share our employment contracts. If the document is rarely customized, then provide the content directly on the site and deprecate the Google Doc.

Video chats

  1. Use video calls if you find yourself going back and forth in an issue/via email or over chat.
  2. Having pets, children, significant others, friends and family visible during video chats is encouraged. If they are human, ask them to wave at your remote team member to say 'Hi'.

Say Thanks

  1. Thank people that did a great job in our 'Thanks' chat channel. If someone is a team member just "@" mention them. If multiple people were working on something try mentioning each person by "@" name. 'Thanks everyone' does not say much.
  2. To thank someone who is not a team member, mention your manager, our People Ops Coordinator, the name of the person, a quirky gift and link to their work. For example: "@manager, @peopleopscoordinator: Joe deserves a lawnmower for LINK". With your manager's blessing, the People Ops Coordinator will approach the person in question for their address saying we want to send some swag. We'll ship it in gift wrap with "Thanks for your great work on LINK, love from @gitlab".
  3. Don't thank the CEO or other executives for something that the company paid for, thank GitLab instead.

Not sure where to go?

If there is something that you want to discuss, but you do not feel that it is a reasonable option to discuss with either your manager or CEO, then you can reach out to any of the other C-level team members or our board member Bruce Armstrong.

GitLab Workflow

  1. Always create an issue for things you work on. If it is worth spending time on, it is worth creating an issue for it since that enables other people to learn and help. You can always edit the description or close it when the problem is something different or disappears.
  2. 'Double link' issues to prevent internal confusion and us failing to report back to the reporters. For example, open an issue with link to ZenDesk and close the issue with copy of the response. Or add 'Report: ' lines to the description with links to relevant issues and feature requests and ensure they are closed and note this with a comment. If you are not responsible for reporting back please do not close an issue, instead reassign it.
  3. If issues are related, crosslink them (a link from each issue to the other one). Put the links at the top of the issues' description with a short mention of the relationship (Report, etc.). If there are more than 2 issues, use one issue as the central one and crosslink all issues to this one. Please, also crosslink between ZenDesk and GitLab issues.
  4. After a discussion about a feature update the issue body with the consensus or final conclusions. This makes it much easier to see the current state of an issue for everyone involved in the implementation and prevents confusion and discussion later on.
  5. Give the community the chance to help. For example: place issues on the feedback tracker, leave comments in rake check tests about what you can run manually and ask 'Can you send a merge request to fix this?'.
  6. Submit the smallest item of work that makes sense. When creating an issue describe the smallest fix possible, put suggestions for enhancements in separate issues and link them. If you're new to GitLab and are writing documentation or instructions submit your first merge request for at most 20 lines.
  7. Do not leave issues open for a long time, issues should be actionable and realistic. If you are assigned but don't have time, assign it to someone else. If nobody is assigned and it is not a priority, please ensure the community can help and close it.
  8. Make a conscious effort to prioritize your work. The priority of items depends on multiple factors: is there a team member waiting for the answer, what is the impact if you delay it, how many people does it affect, etc. This is detailed in the engineering workflow document.
  9. Use the public issue trackers on GitLab.com for everything since we work out in the open. We do still use some private issue trackers on our internal dev.gitlab.org server, such as for organizational issues that do not have a home in one of the public team trackers that can be found on the team structure page.
  10. Pick issues from the current milestone.
  11. We try not to assign issues to people but to have people pick issues in a milestone themselves.
  12. Assign an issue to yourself as soon as you start to work on it, but not before that time. If you complete part of an issue and need someone else to take the next step, re-assign the issue to that person.
  13. When reassigning an issue, make sure that the issue body contains the latest information. The issue body should be the single source of truth.
  14. When working on an issue, ask for feedback from your peers. For example, if you're a designer and you propose a design, ping a fellow designer to review your work. If they approve, you can move it to the next step. If they suggest changes, you get the opportunity to improve your design. This promotes collaboration and advances everyone's skills.
  15. We keep our promises and do not make external promises without internal agreement.
  16. Even when something is not done, share it internally so people can comment early and prevent rework. Mark the merge request Work In Progress so it is not merged by accident.
  17. When you create a merge request, mention the issue(s) that it solves in the description. If any followup actions are required on the issue after the merge request is merged, like reporting back to any customers or writing documentation, avoid auto closing it by saying Fixes #1 or Closes #1.
  18. Once a merge request is created, make sure to assign it to the proper person:
    1. For example a merge request that fixes a frontend issue should have the Frontend label and be assigned to a Frontend Engineer for review. For other workflow labels please see PROCESS.md.
    2. A merge request that is related to Continuous Integration should be assigned to the GitLab CI lead.
    3. All other merge requests should be assigned for review to either a merge request miniboss or endboss. You can find the people with these roles on the team page.
    4. Once a merge request has gone through review by a miniboss, they will assign it to an endboss who will do a final review and perform the actual merge if satisfied.
  19. When you are done with your merge request, remove the WIP prefix and assign the merge request to someone to review and merge it. You can still make changes based on feedback of course, but by removing the WIP prefix it clarifies when the main body of work is completed.
  20. When a merge request is done, set milestone to the version it should be included in.
  21. If you are assigned to review and merge a merge request and would like the creator to make some changes, comment on the merge request and assign it back to the creator. When they have addressed the concern, they will reassign it to the reviewer.
  22. If you are assigned to merge a merge request and there is a merge conflict, consider trying to resolve it yourself instead of asking the merge request creator to resolve the conflict. If it is easy to resolve you avoid a round trip between you and the creator, and the merge request gets merged sooner. This is a suggestion, not an obligation.
  23. If you ask a question to a specific person, always start the comment by mentioning them; this will ensure they see it if their notification level is mentioned and other people will understand they don't have to respond.
  24. Do not close an issue until it is fully done, which means code has been merged, it has been reported back to any customers and the community, all issue trackers are updated and any documentation is written and merged.
  25. When closing an issue leave a comment explaining why you are closing the issue.
  26. If a user suggests an enhancement, try and find an existing issue that addresses their concern, or create a new one. Ask if they'd like to elaborate on their idea in one of these issues.

Team Call

  1. The team call is every workday except Friday from 8:30am to 9:00am Pacific Time (mostly 5:30pm - 6:00pm Central European Time).
  2. Every last Friday of the month we have a AMA to talk about anything our team is thinking about.
  3. We use Zoom for the call since Hangouts is capped at 15 people, link is in the calendar invite, and also listed at the top of the Team Agenda.
  4. The call is recorded automatically, and we have a 1GB limit for recordings which is roughly sufficient for 3 days; after this is full, the recording will not be stored. Recordings can be found by logging on to the Zoom portal using the generic credentials in the Shared vault in 1Password; find "My Recordings". Remember to actively log out after viewing or downloading the recording, otherwise you will appear as the Moderator on subsequent calls.
  5. We start on time and will not wait for people.
  6. Person who has first item on the agenda starts the call.
  7. If you are unable to attend just add your name to the Team Agenda as 'Not attending'.
  8. We start by discussing the subjects that are on the agenda for today.
    • Everyone is free to add subjects. Please start with your name and be sure to link to an issue, merge request or commit if that is relevant.
    • When done with a point mention the subject of the next item and hand over to the next person.
    • When someone passes the call to you, no need to say, “Can you hear me?” Just begin talking. If we can’t hear you, we’ll let you know.
  9. We have functional group updates (1 group per call) for the following groups: Marketing, Sid, Product, Sales, Ops, Support, HR, Finance, Development, Front-end, UX/UI. Please limit the updates to 10 minutes or less.
  10. We ask 15-20 people per day to share updates about the most exciting thing from your past or upcoming week/weekend. If anyone has something they'd like to talk about, last person in the list will ask the group if they have anything else to share.
    • The Team Agenda lists who is meant to speak on which day; this can be altered daily if conflicts arise.
    • There is no need to excuse yourself with "I didn't do anything interesting", "I just watched television" or "that's all", it is not a competition. Instead share the most interesting detail, for example what television show you watched, book you are reading, video game you played or what recipe you cooked.
  11. Sequence of asking people is in order of joining the company, same as on the team page. If there are non-team page people in the call we end with those.
  12. It is OK to talk over people or interrupt people to ask questions, cheer for them or show your compassion. This to encourage more conversation and feedback in the call.
  13. Please look if the person you hand over to is present in the participant list so you don't hand over to someone who is not present.
  14. Last person wishes everyone a good day.
  15. Even if you cannot join the call, consider reviewing the recorded call or at minimum read through the team agenda and the links from there. We often use the team call to make announcements or discuss changes in processes, so make sure to catch up on the news if you have missed a team call (or more).

Random Chat and Room

  1. The #random chat channel is your go-to place to share random ideas, pictures, articles, and more. It's a great channel to check out when you need a mental break.
  2. Come hang out any time in the random room, an open Google Hangout video chat where anyone with a GitLab email address can come and leave as they please. The link is in the description of the #random chat channel; consider bookmarking it. This room is open for all and should be distinct from the Coffee Break Calls, which are 1x1 conversations between teammates.

Scheduling meetings

  1. If you want to ask team members if they are available for an event please send a new calendar appointment from and to the company address. This makes it easier for people to check availability and to put on their calendar. It automatically shows up on calendars even when the email is not opened. It is easier to signal presence and to see the status of everyone. Please respond quickly to invites so people can make plans.
  2. If there are materials relevant for a calendar meeting please add the URL to the meeting invite description. Normally this would be a Google Doc for the agenda and any relevant issues.
  3. Put the agenda in a Google Doc that has edits rights for all participants (including people not part of GitLab Inc.). Take notes of the points and todo's during the meeting. Nobody wants to write up a meeting after the fact and this helps to structure the thought process and everyone can contribute. Being able to structure conclusions and follow up actions in realtime makes a video call more effective than an in-person meeting.
  4. If you want to check if a team member is available for an outside meeting, create a calendar appointment and invite the team member only, after they respond yes then invite outside people.
  5. When scheduling a call with multiple people, invite them using a Google Calendar that is your own, or one specific to the people joining, so the calendar item doesn't unnecessarily appear on other people's calendars.
  6. If you want to move a meeting just move the calendar appointment instead of reaching out via other channels, note the change at the top of the description.
  7. Please click 'Guests can modify event' so people can update the time in the calendar instead of having to reach out via other channels. You can install the Google-Calendar-Guests-Can-Modify-Event-By-Default plugin in Chrome to do this automatically.
  8. If you want to schedule a meeting with a person not on the team please use Calendly.
  9. When scheduling a meeting we value people's time and prefer the "speedy meetings" setting in our Google Calendar. This gives us meetings of, for example, 25 or 50 minutes leaving some time to write notes etc before continuing to our next call or meeting. (This setting can be found under the calendar Settings menu at "default event duration")
  10. When creating a calendar event that will be used company wide, please place it on the GitLab Availability Calendar. That way the event is easily located by all individuals.

Video calls

  1. For smaller meetings we use Google Hangouts, for larger meetings we prefer Zoom (Google Hangouts technical limit is 15 for scheduled meetings).
  2. For meetings that are scheduled via calendar there is automatically a Google Hangout URL added, this is the meeting place. Having a url in advance is much more reliable than trying to call via hangouts as the meeting start.
  3. Use a headset with a microphone, Apple Earpods are great. Do not use computer speakers, they cause an echo. Do not use your computer microphone, it accentuates background noise. If you want to use your Bose headphones that is fine but please ensure the microphone is active.
  4. Consider using a utility to easily mute/unmute yourself, see Shush in the tools section.
  5. In video calls everyone should own camera and headset, even when they are in the same room. This helps to see the person that is talking clearly on the camera and their name in the list. It also allows people to easily talk and mute themselves. And using a headset prevents an echoing. You wouldn't share an office seat together, don't share your virtual seat at the table.

User Communication Guidelines

  1. Keep conversations positive, friendly, real, and productive while adding value.
  2. If you make a mistake, admit it. Be upfront and be quick with your correction. If you're posting to a blog, you may choose to modify an earlier post, just make it clear that you have done so.
  3. There can be a fine line between healthy debate and incendiary reaction. Try to frame what you write to invite differing points of view without inflaming others. You don’t need to respond to every criticism or barb. Be careful and considerate.
  4. Answer questions, thank people even if it’s just a few words. Make it a two way conversation.
  5. Appreciate suggestions and feedback.
  6. Don't make promises that you can't keep.
  7. Guide users who ask for help or give a suggestion and share links. Improving Open Development for Everyone, Types of requests.
  8. When facing negative comment, respond patiently and treat every user as an individual, people with the strongest opinions can turn into the strongest supporters.

Writing Style Guidelines

  1. Do not use rich text, it makes it hard to copy/paste. Use Markdown instead.
  2. We use Unix style (lf) line endings, not Windows style (crlf), please ensure *.md text eol=lf is set in the repository's .gitattributes and run git config --global core.autocrlf input on your client.
  3. Do not create links like "here" or "click here". All links should have relevant anchor text that describes what they link to, such as: "GitLab CI source installation documentation".
  4. Always use ISO dates in all writing and legal documents, yyyy-mm-dd, e.g., 2015-04-13, and never 04-13-2015 or 13-04-2015
  5. If you have multiple points in a comment or email, please number them to make replies easier.
  6. When you reference an issue, merge request, comment, commit, page, doc, etc. and you have the URL available please paste that in.
  7. In URLs, always prefer hyphens to underscores.
  8. The community include users, contributors, core team members, customers, people working for GitLab Inc., and friends of GitLab. If you want to refer to 'people not working for GitLab Inc.' just say that and don't use the word community. If you want to refer to people working for GitLab Inc. you can also use 'the GitLab Inc. team' but don't use the 'GitLab Inc. employees'.
  9. All people working for GitLab the company are the GitLab team, we also have the Core team that is part GitLab team, part volunteers.
  10. Please always refer to GitLab Inc. people as team members, not employees.
  11. Use inclusive and gender-neutral language in all writing. So for example, write "they, their" instead "he, his".
  12. Always write GitLab with a capitalized G and L, even when writing GitLab.com.
  13. Monetary amounts shouldn't have one digit, so prefer $19.90 to $19.9
  14. If an email needs a response write the ask at the top of it.
  15. Use the future version of words, just like we don't write internet with a capital anymore, we write frontend and webhook without a hyphen or space.
  16. Our homepage is https://about.gitlab.com/ (with the about. and with https).
  17. Try to use the active voice whenever possible.
  18. Please refer to self-hosted installations as on-premises, not on-premise.
  19. If you use headers properly format them (## in Markdown, "Heading 2" in Google docs), start at the second header level because header level 1 is for titles, do not end headers with a colon.
  20. Always use an Oxford comma in lists of three or more terms.
  21. Always use a single space between sentences rather than two.
  22. Read our Documentation Styleguide for more information when writing documentation.
  23. Do not use acronyms when you can avoid it as you can't assume people know what you are talking about. Example: instead of MR, write merge request.

Beamy Guidelines

Beamy is our company conference call robot. It lives in the San Francisco Howard St. office. Its main purpose is to allow those outside of the office a view into the space and people. When you call in to the beam your face will appear on the screen (so make sure your webcam works) and you can drive the robot around the office. It simulates being in the space without physically being there. It is really cool and everyone should try it and have fun with it.

Company phone number

If you need to provide the details of GitLab's contact information you can take the address of the office for reference; or the mailing address of the office in the Netherlands if that is more applicable.

If a phone number is required, leave this field empty by default. If that is not possible, then use the general number (+1-415-761-1791), but be aware that this number simply guides to a voice message that refers the caller back to contacting us via email.

On-Call Rotation and Scheduling

We have on-call heroes (see the team page) to respond quickly to GitLab.com downtime, and customer emergencies. Details about the schedule and how to swap duty in the On-Call page.

Intellectual Property

  1. Take proper care of any confidential information you get from our customers.
  2. If you copy code always check the license and attribute when needed or appropriate.
  3. Check community contributions and do not merge it when there can be doubt about the ownership.
  4. Only the CEO of the company signs legal documents such as NDAs. Sales people and the business office manager can upload them via HelloSign.
  5. View our DMCA policy in regards to copyright / intellectual property violations
  6. Comply with the GitLab Inc. Proprietary Information and Assignment Agreement and/or GitLab B.V. NDA and IP Agreements.

Spending Company Money

In keeping with our values of results, freedom, efficiency, frugality, and boring solutions, we expect team members to take responsibility to determine what they need to purchase or expense in order to do their jobs effectively. We don't want you to have to wait with getting the items that you need to get your job done. You most likely know better than anyone else what the items are that you need to be successful in your job. The guidelines below describe what people in our team commonly expense.

  1. Spend company money like it is your own money.
  2. You don't have to ask permission before making purchases in the interest of the company. When in doubt, do inform your manager before the purchase, or as soon as possible after the purchase.
  3. It is uncommon for you to need all of the items listed below, use your best judgement and buy them as you need them. If you wonder if something is common, feel free to ask People Ops (and in turn, People Ops should update the list).
  4. It is generally easiest and fastest for you to make the purchases yourself, but feel free to reach out to People Ops if you would like help in acquiring some items. Just include a link and your shipping address in an email, and People Ops will be happy to place the order.
  5. Employees: file your expense report no later than 7 days after the end of the calendar quarter that you made the purchase in. Contractors: include receipts with your invoices.
  6. Any non-company expenses paid with a company credit card will have to be reported to your manager as soon as possible and refunded in full within 14 days.
  7. Items. The company will pay for the following items if you need it for work or use it mainly for business, and local law allows us to pay for it without incurring payroll taxes. Items paid for by the company are property of the company and need to be reported with serial numbers etc. to People Ops for proper asset tracking. Since these items are company property, you do not need to buy insurance for them unless it is company policy to do so (for example, at the moment we do not purchase Apple Care), but you do need to report any loss or damage to PeopleOps as soon as it occurs. Links in the list below are to sample items, other options can be considered:
    • Notebook: we recommend getting a MacBook Pro 13-inch retina with 512GB of storage and 16GB of memory for engineers and a Macbook 256GB for non-engineers. Running Unix makes it easier to work with git from the command line so we strongly recommend against Windows laptops. WebEx screen sharing does not work from a Linux platform while it is one of the more common conferencing tools used with customers that we all need to interact with from time to time. Additionally 1password doesn't have a native client for Linux and the web interface in Firefox is not that good. If you have strong reasons to want to deviate from this guideline just ask your manager.
    • Notebook carrying bag
    • External monitor, monitor-cable,
    • Webcam
    • Ethernet connector
    • Headset
    • Keyboard and mouse set
    • Height adjustable desk
    • Ergonomic chair
    • Notebook stand
    • Work-related books
    • Mobile phone, we commonly pay for an iPhone SE if you travel a lot as a Developer Advocate.
    • Yubikey
    • Something else? No problem, and consider adding it to this list if others can benefit as well.
  8. Expenses. The company will reimburse for the following expenses if you need it for work or use it mainly for business, and local law allows us to pay for it without incurring taxes:
    • Mileage is reimbursed according to local law: US rate per mile, or rate per km in the Netherlands.
    • Internet connection, for employees in the Netherlands see Regeling Internet Thuis. Send the signed form to People Ops once completed.
    • Mobile subscription, we commonly pay for that if you call a lot as a salesperson or executive.
    • Telephone land line (uncommon, except for positions that require a lot of phone calls)
    • Skype calling credit, we can autofill your account (uncommon, since we mostly use Google Hangouts, Zoom, and WebEx)
    • Google Hangouts calling credit
    • Office space (if working from home is not practical)
    • Work-related online courses
    • Work-related conferences, including travel, lodging and meals. If total costs exceed $500, please submit a proposal and get permission from your manager.
    • Travel and lodging to get together with colleagues and work on a specific project, with a minimum of 3 team members present and 3 days of co-location. Meals are generally not covered out of fairness to any people already on location. If total costs exceed $300, please submit a proposal to your manager and get permission from them and the VP of your department.
    • Business travel upgrades per round-trip (i.e. not per each leg of the flight):
      • Up to the first EUR 300 for an upgrade to Business Class on flights longer than 8 hours.
      • Upgrade to Economy Plus if you’re taller than 1.95m / 6’5” for flights longer than 2 hours.
      • Up to the first EUR 100 for an upgrade to Economy Plus (no height restriction) on flights longer than 8 hours.
    • Something else? No problem, and consider adding it to this list if others can benefit as well.
  9. Expense Reimbursement
    • If you are a contractor, please submit an invoice with receipts attached to ap@gitlab.com.
    • If you are an employee, GitLab uses Expensify to facilitate the reimbursement of your expenses. As part of onboarding you will receive an invitation by email to join GitLab's account. Please set up your account by following the instructions in the invitation.
    • If you are new to Expensify and would like a brief review, please see Getting Started
    • For step by step instructions on creating, submitting and closing a report please see Create, Submit, Close
    • If you are an employee with a company credit card, your company credit card charges will automatically be fed to a new Expensify report each month. Please attach receipts for these expenses (per the Expense Policy, see below) within 5 business days after the end of the month. These amounts will not be reimbursed to you but Expensify provides a platform for documenting your charges correctly.
    • Expense Policy
      • Max Expense Amount - 5,000 USD or 5,000 EUR
      • Receipt Required Amount - 25 USD or 25 EUR
  1. Don't frown on people taking time off, but rather encourage that people take care of themselves and others.
  2. Working hours are flexible, you are invited to the team call if you are available, and we encourage you to post to the #working-on chat channel when you start your day so others can offer suggestions.
  3. You don't need to worry about taking time off to go to the gym, take a nap, go grocery shopping, doing household chores, helping someone, taking care of a loved one, etc. If something comes up or takes longer than expected and you have urgent tasks and you're able to communicate, just ensure the rest of the team knows and someone can pick up any urgent tasks.
  4. We have an "unlimited" time off policy. This means that:
    • You do not need to ask permission to take time off unless you want to take more than 25 consecutive calendar days.
    • Always make sure that your job responsibilities are covered while you are away.
    • We strongly recommended to take at least a minimum of 2 weeks of vacation per year, if you take less your manager might follow up to discuss your work load.
  5. You do need to ensure that not more than half of the people that can help with availability emergencies (the on-call heroes), regular support, sales, or development are gone at any moment. You can check for this on the availability calendar, so be sure to add appointments early.
  6. Please see the On-Call page for information on how to handle scheduled leave for someone from the on-call team.
  7. Add an appointment to the GitLab availability calendar as you know your plans, you can always change it later.
  8. In case it can be useful add your planned time off as a FYI on the next agenda of the team call.
  9. We will help clients during official days off, unless they are official days off in both the Netherlands and the U.S. We try to have people working who are in a country that don't have an official day off. If you need to work during an official day off in your country, you should take a day off in return.
  10. If you have to respond to an incident while being on-call outside of your regular working hours, you should feel free to take off some time the following day to recover and be well-rested. If you feel pressure to not take the time off to rest, refer to this part of the handbook and explain that you had to handle an incident.

Incentives

The following incentives are available for GitLab team members. Also see our separate page on benefits available to GitLab team members.

Sales Target Dinner Evangelism Reward

Since reaching sales targets is a team effort that integrates everything from making a great product to providing top notch customer support and everything in between, we reward all team members (not just the Sales team) for every month that we reach our Sales Targets. The incentive is 100 USD to each team member for the purpose of evangelizing the GitLab story. You may use the incentive at a restaurant of your choice. Enjoy!

Discretionary Bonuses

  1. Every now and then, individual team members really shine as they go above and beyond their regular responsibilities and tasks.
    • We recognize this through the #thanks channel, and sometimes also through a discretionary bonus.
    • Managers can recommend their team members to the CEO for a $1,000 bonus.
    • On team call, the manager announces the “who” and “why” of the bonus; and the "why" should be tied to our values.
    • The manager should send a brief email that explains the bonus (same as the team call blurb) and states the amount to People Ops and our Controller who will process the information into payroll and BambooHR. People Ops should confirm when these steps have been taken, back to the manager.
  2. If you think you are meeting the requirements for another title, want to change jobs within the company, or think your growth should be reflected in your compensation please feel free to discuss with your manager.

Referral Bonuses

Chances are that if you work at GitLab, you have great friends and peers who would also be fantastic additions to our Team and who may be interested in one of the current Job Openings. To help us grow the team with exceptional people, we have referral bonuses that work as follows:

  1. If you refer a great candidate and they are hired, then you receive a $1,000 bonus once the new team member has been with the company for 3 months.
  2. If the new team member receives a discretionary bonus within the first 6 months of their hire, then you also get a $1,000 bonus.
  3. Exceptions: no bonuses for hiring people who report to you, and no bonus for the executive team.
  4. When your referral applies for an opening, make sure that they enter your name on the application form.

People Ops will process the bonus.

Work Remotely Travel Grant

GitLab is a remote-first company with team members all over the world (see the map on our Team page ). If you want to visit a colleague in another part of the world, or promote GitLab at events in another country, then present your travel plan to your manager or the CEO, and you can receive up to $2,000 in support for your plan!

As an example, the first grant was handed to a team member who will be traveling to 6 team members in different countries during 6 months, and this team member will receive the maximum grant of $2,000.

To claim the approved award, include a line item on your expense report or invoice with the approval email as the receipt. The entire award can be claimed from the first month of travel to up to 3 months after the travel is completed.

Only C-level executives can sign legal documents, with the exception of NDAs covering a physical visit of another organization. When working with legal agreements with vendors, consultants, and so forth, bear in mind the signature authorization matrix. If you need to sign, fill out, send or retrieve documents electronically, please send a description of what you need or a copy of the document to legal@gitlab.com with the following information:

  1. Names and email addresses of those who need to sign the document.
  2. Any contractual information that needs to be included in the document.
  3. Deadline (or preferred timeline) by which you need the document prepared (i.e. staged in HelloSign for relevant signatures)
  4. Names and email addresses of those who need to be cc-ed on the signed document.

The process that "legal" (currently a combination of People Ops and Finance) will follow is:

  1. Prepare the document as requested.
  2. Have the requestor check the prepared document, AND obtain approval from the CFO or CEO (such approval may be explicit in the email thread that was sent to legal@, in which case a second approval is not needed unless there have been significant edits to the document).
  3. Stage the document for signing in HelloSign and cc (at minimum) the requestor and legal@.
  4. Once signed, the person who staged it in HelloSign places the document in the contracts folder on Google Drive.

Working remotely

Working remotely has a lot of advantages, but also a couple of challenges. The goal of this section is to provide information and tips to maximize the advantages and make you aware of the challenges and provide tips on how to deal with them.

Probably the biggest advantage of working remotely and asynchronously is the flexibility it provides. This makes it easy to combine work with your personal life although it might be difficult to find the right balance. This can be mitigated by either explicitly planning your time off or plan when you do work. When you don't work it is recommended to make yourself unavailable by turning off Slack and closing down your email client. Coworkers should allow this to work by abiding by the communication guidelines.

If you worked at an office before, now you lack a default group to go out to lunch with. To look at it from a different perspective, now you can select who you lunch with and who you do not lunch with. Haven't spoken to a good friend in a while? Now you can have lunch together.

Coffee Break Calls

Understanding that working remotely leads to mostly work-related conversations with fellow GitLabbers, everyone is encouraged to dedicate a few hours a week to having social calls with any GitLab employee - get to know who you work with, talk about everyday things and share a virtual cuppa' coffee. We want you to make friends and build relationships with the people you work with to create a more comfortable, well-rounded environment. The Coffee Break calls are different to the Random Room video chat, they are meant for give you the option to have 1x1 calls with specific teammates you wish to speak with and is not a random, open-for-all channel but a conversation between two teammates.

Tools and Tips

A lot of tools we use are described in the rest of the handbook (GitLab, Google Docs, Google Hangouts, 1Password, etc.). This section is for tools that don't fit anywhere else.

Calendly

Calendly connects to your Google calendar so people can book a time with you without having a Google Account.

  1. Set up a Calendly account
  2. Link it to your GitLab Google Calendar to make it possible for people to schedule a call with you
  3. All meetings will have the same Google Hangout URL on your calendar based on your @gitlab.com email handle. You can use that in the booking text above. Events on your calendar will automatically have the Google Hangout URL added, so you can use the plus landing page to quickly jump into the call. Please note that the appointment will show up in other peoples calendar with a different link, to it is essential that you set a text with the link for your time slot as specified below.
  4. Set up the 45 minute time slot with the following event description text (replacing XXXXX with your @gitlab.com handle):

    This will be a Google Hangout at https://plus.google.com/hangouts/_/gitlab.com/XXXXX

    Question? Please email me. GitLab Primer: https://about.gitlab.com/primer/

  5. If you intend to use any of the other event types, make sure to add this to their event descriptions as well.
  6. For people outside of GitLab Inc, send them your Calendly link that links directly to the 45 minute time slot: "Are any of the times on https://calendly.com/XXXXX/45min/ convenient for you? If so please book one, if not please let me know what times are good for you and we'll find an alternative."
  7. Update your availability on Calendy Event Types
  8. Add your Calendly link to your Slack profile. For Display Text, use this line: Schedule a meeting with me! so team members can schedule a 1:1 call with you in GitLab, by simply clicking your Calendly link in your Slack profile.

Keep in mind that unlike normal Google Calendar events, Calendly events are not automatically synchronized between both parties when changes are made. If an event needs to be cancelled or modified, make sure to use Calendly to do so.

Shush

$4.99 tool for OSX that allows you to use you fn key as a push to talk or push to mute. Never again will you have switch window focus to Google Hangout or Zoom to speak or mute. The icon will show the current state of your mic input (x means muted). With a right click you can switch from push to talk to push to mute. Don't forget to unblock your mic in Zoom/Google Hangouts immediately after joining. Be warned that page up with fn+down arrow will activate it. Use space for page down instead of fn+up arrow.

Disabling OS X Notification Center

During a presentation or screen share, you might want to disable your notifications on OS X to prevent distractions or possible embarrassment.

The Notification Center can be quickly disabled by Option-Clicking the menu bar icon in the top right of your screen. This disables notifications until the next day. Option-Click again to re-enable immediately. Alternatively, click on the Notification Center icon, then scroll up to reveal the "Do Not Disturb" toggle.

Google Calendar Guest Modify Event Default

This Chrome extension will allow guests to modify calendar appointments by default.

Zoom

To set up a Zoom meeting, sign up for a free Basic account, and share the link for your "personal meeting room" with your participants. Note that on the Basic license, meetings are capped at 50 people, and meeting durations are capped at 40 minutes. If you need additional duration, reach out to People Ops to see if we can extend the existing Pro license that is in use to manage the team call.

To record the meeting, simply click on record, which will save an .mp4, .mp3, and .txt files for chat, to your local hard drive.

Please add instructions on how to add the resulting video to our YouTube channel.

Gmail

Filters

It might be useful to add a Gmail filter that adds a label to any GitLab notification email in which you are specifically mentioned, as opposed to a notification that you received simply because you were subscribed to the issue or merge request.

  1. Search for @your_gitlab_username in Gmail
  2. Click the down arrow on the right side of the search field
  3. Click "Create filter with this search"
  4. Check "Apply the label:" and select a label to add, or create a new one, such as "Mentioned"
  5. Check "Also apply filter to matching conversations."
  6. Click "Create filter"

If your username on dev.gitlab.org is different from your username on GitLab.com, you might want to create a similar filter for that username as well.

Advance

If you use the archive function you normally return to your overview. With auto-advance you can return to the next message. Enable 'Auto-advance' in the labs section under settings. The default setting of showing the next older message is OK.

Hangouts

In Chrome Hangouts tends to consume 100% of CPU due to use of the vp9 codec. On MacOS switching to Safari solves this since it will use h264 that is hardware accelerated.

Hangouts on air

Hangouts on Air probably only works with a maximum of 15 people for scheduled calls (same limit as normal Google Hangouts).

Potential problem: even when I logged in as GitLab and got the bar below the call, I could not switch it too on-air! I did notice that the time was not properly set (anymore?). I did a test event before and that seemed to work OK. I'll try one more time to see if it works.

Potential problem 2: the video showed up as listed by default

Go to My live events on YouTube and switch to the GitLab account on the top right (you need to be a manager of our YouTube channel).

Go to => life streaming => events and create a new one with the attributes:

The view on watch page URL only allows for people to watch it. Window that pops up when you press the start hangout on air button has the proper URL that you can send to other people and/or add it to the calendar invite, it is structured like: https://plus.google.com/hangouts/_/ytl/LONGHASH. When people join the event they have to accept a warning.

Completed live events will show the video and you can click the image to view it. You can use actions to make it public here

BTW Trying to set this up via Google+ via https://plus.google.com/hangouts/onair instead of via YouTube doesn't seem to connect to the right YouTube channel, even if you selected the right account on the top right.

One Tab

One Tab tames tabs into a list which can be sorted and exported.

Quitter

Quitter will switch off apps for you after some period of inactivity. Consider using this to hide Slack after a while to reduce your urge to check new messages all the time.

TripMode

TripMode lets you control which apps can use the internet. Especially useful when you're working on a cellular/metered connection.

Check which process occupies a given port

When the GitLab Development Kit cannot start using the ./run command and Unicorn terminates because port 3000 is already in use, you will have to check what process is using it. Running sudo lsof -i -n -P | grep TCP | grep 3000 will yield the offender so this process can be killed. It might be wise to alias this command in your .bash_profile or equivalent for your shell.

MobileDay

If you install MobileDay on your phone and give it access to your Google Calendar it can dial into conference calls for you. It is very good at detecting the number and password from the calendar invite.

Visual help to differentiate between GitLab servers

If you are working on multiple GitLab instances and want to have a visual differentiation, you can change the default Application theme to a different color.

How to change your username at GitLab.com

STEP 1: Request your new username

STEP 2: Create a new account with your new username

STEP 3: Let's have some fun (kidding, this is critical!)

STEP 4: Move your projects (or not)

That's it! Don't forget to update your username on the team page and on the Marketing Handbook, in case you're a Marketing Team member.

Do NOT Use

Flash: Due to security flaws, we strongly recommend not using Adobe Flash. Certainly do not install it on your local machine. But even the Google Chrome plugin that let's you see embedded Flash content in websites can pose a security hazard. If you have not already, go to your Chrome plugins and disable Flash. For further context, note that Google Chrome is removing Flash support soon, and while the plugin is better than a local install of Flash, it still leaves vulnerabilities for zero-day attacks.

Using Git to update this website

For more information about using Git and GitLab see GitLab University.

This is a guide on what you'll need to install and run on your machine to get Git up and running so you can create your first merge request in minutes! Follow the numbered steps below to complete your setup.

1. Start using GitLab

  1. Here's where you can find step-by-step guides on the basics of working with Git and GitLab. You'll need those later.
  2. Create your SSH Keys.

2. Install Git

  1. Open a terminal.
  2. Check your Git version by executing: git --version.
  3. If Git is not installed, you should be prompted to install it. Follow this guide to installing Git and linking your account to Git.

3. Install RVM

  1. Visit https://rvm.io.
  2. In a terminal, execute: curl -sSL https://get.rvm.io | bash -s stable.
  3. Close terminal.
  4. Open a new terminal to load the new environment.

4. Install Ruby and Bundler

  1. In a terminal, execute: rvm install 2.2.1 to install Ruby (enter your system password if prompted).
  2. Execute: rvm use 2.2.1 --default to set your default Ruby to 2.2.1.
  3. Execute: ruby --version to verify Ruby is installed. You should see: ruby 2.2.1p85 (2015-02-26 revision 49769).
  4. Execute: gem install bundler to install Bundler.

5. Clone the source of the website and install its dependencies

  1. In a terminal execute: git clone https://gitlab.com/gitlab-com/www-gitlab-com.git to clone the website.
  2. Execute: cd www-gitlab-com to change to the www-gitlab-com directory.
  3. Execute: bundle install to install all gem dependencies.

6. Prevent newlines from causing all following lines in a file to be tagged as changed

This is especially a problem for anyone running a Mac OSX operating system. The command to 'tame' git is git config --global core.autocrlf input - execute it.

7. Start contributing

Instructions on how to update the website are in the readme of www-gitlab-com.

Most pages that you might want to edit are written in markdown Kramdown. Read through our Markdown Guide to understand its syntax and create new content.

Local Checks of Your Changes

1. Preview website changes locally

  1. In a terminal, execute: bundle exec middleman.
  2. Visit http://localhost:4567 in your browser.
  3. To edit the site locally you'll need to install a text editor. We recommend Sublime Text 3 or Atom.

Until this is automated in CI, a quick way to see if there are any invalid links inside a page is the following.

  1. Install the check-my-links extension in Chrome (no other browsers support unfortunately).
  2. Open the page you wish to preview (see previous step).
  3. Click the newly installed extension in the upper right corner of Chrome.

A pop-up window will open and tell you how many links, if any, are invalid. Fix any invalid links and ideally any warnings, commit, push back, test again.