Skip to content

Latest commit

 

History

History
182 lines (117 loc) · 5.87 KB

CONTRIBUTING.md

File metadata and controls

182 lines (117 loc) · 5.87 KB
Raw

Contributing

Thank you for considering contributing to Workbench. Feel free to get in touch.

Setup

The following is the recommended setup:

  1. Install GNOME Builder from Flathub
  2. Open Builder and select "Clone Repository..."
  3. Clone https://github.com/sonnyp/Workbench.git (or your fork)
  4. Press the Run ▶ button

Make sure that you're building the development target re.sonny.Workbench.Devel.

ℹ️ Select "Blueprint" instead of "XML" in Workbench UI panel. Blueprint is experimental but that's what we use for making Workbench.

If you know what you are doing you can also use VSCode with the extensions recommended in this workspace or anything else you are comfortable with. Don't forget to fetch the submodules.

Install development dependencies

We provide a couple of tools to make the development process pleasant.

  • Code formatter that runs automatically on git commit
  • Single command to run all the tests locally
# Ubuntu requirements
# sudo apt install flatpak nodejs gettext make
# Fedora requirements
# sudo dnf install flatpak nodejs gettext make

cd Workbench
make setup

Before submitting a PR, we recommend running tests locally with

make test

Getting started

If you're completely new to GNOME development this is for you.

Open the "Welcome" example from Workbench Library.

Important fundamentals are

  • objects
  • properties
  • signals

Every widget in GTK is an object. For example, Gtk.Box, Gtk.Button, ...

Properties affect an object to change its appearance or behavior.

Signals are events that can be listened to. Like clicked on Gtk.Button.

The Welcome example in the Library has all 3. Play with it, try to understand and make changes. If you break things you can always go back by select "Welcome" example from the Workbench Library again.

Once you understand these 3 things, try creating something new. There are plenty of widgets and patterns to explore.

Your first contribution

Your first contribution should be a new example or demo for the Workbench library.

Library examples and demos have 3 functions

  1. Showcase the capabilities of the platform
  2. Teach how to use the APIs, patterns and widgets
  3. Provide functional snippets ready to use

Pick a widget and make a Library demo for it within Workbench directly.

Check here for ideas and here for examples.

Feel free to reach out and ask for a topic or feedback.

Some guidelines

  • Start with something small and accessible
  • Focus on quality over quantity
  • Make sure you don't pick something deprecated or soon to be
  • Select "Blueprint" instead of "XML" in the UI panel
  • Keep it concise and interactive
  • Add links to follow up on the topic covered
  • Follow the patterns of existing entries
  • Follow the Style Guide

Create Library entry

To create a new Library entry, duplicate an existing one and proceed to the next section.

cp -r src/Library/demos/Button src/Library/demos/Something

Update Library entry

To update or port an existing Library entry

  1. Open Workbench
  2. Select "Open Project…" in the menu
  3. Select the corresponding Library folder, for example Workbench/src/Library/demos/Something
  4. Make the changes

Submitting a contribution

Once you're satisfied with the result - you can send a pull request to include it in Workbench.

Some guidelines:

  • Unless you don't want too - add your name to the list of contributors
  • Use a short PR title - eg. "library: Add Video entry" - it will be used as commit message
  • If relevant, mention the related issue in the PR description
  • Test your code before asking for review, for example by starting Workbench and opening the Libary entry
  • Always review your own work before asking someone else

Learn

Here is a compilation of resources to learn more about the GNOME platform.

Debugging

To view debug logs, use the following command in src/workbench.

--command "G_MESSAGES_DEBUG=\"@app_id@\" @app_id@ $@"

See also

Troubleshooting

The app won't build/run anymore - even on clean main

Clean the build directory. On GNOME Builder, open the search palette with Ctrl+Enter and search/select Clean.

If that doesn't solve it - remove the GNOME Builder cache directory

rm -r ~/.var/app/org.gnome.Builder/cache/

git says blueprint-compiler is modified

Update submodules.

On GNOME Builder, open search palette with Ctrl+Enter and search/select Update Dependencies...

or

cd workbench
git submodule update