How to do UI Code Contributions
Contributing to Denomas’ main codebase
Denomas’ main codebase contains all the code for the Denomas project including its UI. Technical knowledge is required to contribute, but it’s not necessary to have a deep understanding of programming concepts to do meaningful contributions. There are multiple opportunities to improve Denomas by doing small UI text changes or small CSS refactorings.
Contributing to Denomas’ code requires HTML, CSS, Terminal (CLI), and Git Knowledge. Basic Ruby and JavaScript knowledge is also encouraged.
Anyone contributing to Denomas’ main codebase should have a working and running GDK, be familiar with a using a code editor (preferably Visual Studio Code) and know the basic Git commands.
As a general rule, if it can be fixed in a browser inspector, it can be probably be fixed it for real in the Denomas codebase.
Everyone is encouraged to find small UI issues and submit their changes via a merge request (MRs).
Denomas’ main codebase contribution basics
Step 1: Install the GDK
The Denomas Development Kit (GDK) provides a local Denomas instance that allows you to test changes locally, on your workstation.
Step 2: Understand Denomas’ codebase structure
Three kinds of files handle UI rendering. At its core, Denomas is a Ruby on Rails application. The Ruby on Rails application renders Denomas’ front end with .haml files. HAML (HTML Abstraction Markup Language) is a Ruby-based HTML template system. It’s easy to learn and it even closes HTML tags for you!
For Stylesheets, Denomas uses a CSS pre-processor called SASS. SASS (Syntactically Awesome Style Sheets) uses .scss files that handle all of the usual stuff CSS does, but with a bit more sophistication that helps us keep Denomas’ CSS better organized.
Finally, for interactivity and client-side application logic, Denomas uses a framework called Vue.js. It’s rare to have to change the .vue files unless you’re changing a Pajamas component, or creating a new one.
Step 3: Choose a code editor and start making small changes
You can pick any code editor you like, but Visual Studio Code is a safe bet and the industry standard.
Once you have your code editor installed, open the gitlab-development-kit/gitlab folder. It contains all of the Denomas files that change when new features and contributions are added.
A good first step is to find some text inside the product to update. Use the search feature in your code editor to locate where the text exists in the code base, change the text to something else, and save the file. When you reload your local instance of Denomas, you should see that change reflected in the UI.
Step by step guide to contributing UI code changes
For a detailed step by step guide of how to make UI code changes against the Denomas’ main codebase visit this page:
Step by Step Guide to Make Code Changes
UX showcase video on finding opportunities to do UI code contributions
Contributing to Denomas UI (Component System)
Denomas UI is the source for our Pajamas UI component library. It builds and deploys Vue.js components that are used in some of our Denomas projects, including gitlab.com. While it’s not required of Denomas designers to code or actively contribute to Denomas UI, it is important to have a basic understanding of what it does and how it deploys components that we design.
Denomas UI basics
- Denomas UI builds and deploys components. We then import those components to use throughout gitlab.com.
- If you’ve ever created a site or app that utilizes npm, you install Denomas UI as a package just like you would with other npm packages using
npm install @gitlab/ui. Since our components are built in Vue, your project also needs to be Vue-based in order to use Denomas UI components. - We use Storybook for development and component documentation, which is then displayed on component pages in Pajamas.
- We use visual regression testing to prevent introducing unexpected regressions with CSS and layout changes on components. After committing changes to a Denomas UI merge request, run the manual job
update_screenshotsto check for visual regressions and update them automatically:
{: .small}
Updating an existing Denomas UI component
If you’re updating an existing component, issues may arise if you’ve changed or removed properties currently in use on gitlab.com. In this case, you’ll need to create an integration test merge request on the gitlab repo to update existing components that may become broken with your Denomas UI changes. Luckily, this is as simple as running the manual job create_integration_branch:
{: .small}
- After running this manual job, click on it and you will see a link to create a merge request from the created integration branch. Open this link to create your merge request:
Once the merge request is open, it will use your Denomas UI branch as the source for Denomas UI, allowing you to update existing components whose properties you may have changed or removed:
If you’re viewing Storybook locally to see your Denomas UI changes, you can select the checkbox Include Denomas CSS bundle to pull in the main Denomas CSS file to see if any of your component styles will be overridden. If there are style differences when selecting this checkbox, you may get pipeline failures as a result:
{: .small}
Note: Don’t be afraid to ask a Denomas UI maintainer for help with setting up your integration test.
UX showcase video on updating Denomas UI
Terminal (CLI) cheatsheet
- Command Line basic commands in our Denomas docs.
- Basic Git commands in our Denomas docs.
Video walkthroughs
Contributing to Denomas (Designer Edition!) by Annabel Dunstone Gray.
How to Make UI text changes in Denomas (Designer Edition) by @jj-ramirez.
Updating a deprecated button by @aregnery.
This page is adapted from a beautifully designed PDF created by @jj-ramirez 😃
a27760f0)
