Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
139 lines (88 loc) · 5.04 KB

CONTRIBUTING.md

File metadata and controls

139 lines (88 loc) · 5.04 KB

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.

ℹ️ Please 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.

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
  • in Code, use properties (widget.senstitive) over methods (widget.set/get_sensitive)

Submitting a contribution

Once you're satisfied with the result - you can send a pull request to include it in Workbench. You will need to copy the code into new files in src/Library/demos.

Make sure it's working by running Workbench and launching your entry via the Library. If not - double check what you did and compare with other Library entries.

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

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