diff --git a/HACKING b/HACKING.md similarity index 93% rename from HACKING rename to HACKING.md index 575be5b7a..8c064999a 100644 --- a/HACKING +++ b/HACKING.md @@ -1,19 +1,16 @@ -Coding guide -============ +# Coding guide Our goal is to have all JavaScript code in GNOME follow a consistent style. In a dynamic language like JavaScript, it is essential to be rigorous about style (and unit tests), or you rapidly end up with a spaghetti-code mess. -A quick note ------------- +## A quick note Life isn't fun if you can't break the rules. If a rule seems unnecessarily restrictive while you're coding, ignore it, and let the patch reviewer decide what to do. -Indentation and whitespace --------------------------- +## Indentation and whitespace Use four-space indents. Braces are on the same line as their associated statements. You should only omit braces if *both* sides of the statement are @@ -22,7 +19,7 @@ on one line. * One space after the `function` keyword. No space between the function name * in a declaration or a call. One space before the parens in the `if` * statements, or `while`, or `for` loops. - +```javascript function foo(a, b) { let bar; @@ -39,22 +36,20 @@ on one line. print(20); } } +``` -Semicolons ----------- +## Semicolons JavaScript allows omitting semicolons at the end of lines, but don't. Always end statements with a semicolon. -js2-mode --------- +## js2-mode If using Emacs, do not use js2-mode. It is outdated and hasn't worked for a while. emacs now has a built-in JavaScript mode, js-mode, based on espresso-mode. It is the de facto emacs mode for JavaScript. -File naming and creation ------------------------- +## File naming and creation For JavaScript files, use lowerCamelCase-style names, with a `.js` extension. @@ -67,14 +62,13 @@ library name followed by a dash, e.g. `shell-app-system.c`. Create a `-private.h` header when you want to share code internally in the library. These headers are not installed, distributed or introspected. -Imports -------- +## Imports Use UpperCamelCase when importing modules to distinguish them from ordinary variables, e.g. - +```javascript const GLib = imports.gi.GLib; - +``` Imports should be categorized into one of two places. The top-most import block should contain only "environment imports". These are either modules from gobject-introspection or modules added by gjs itself. @@ -85,7 +79,7 @@ e.g. `imports.ui.popupMenu`. Each import block should be sorted alphabetically. Don't import modules you don't use. - +```javascript const GLib = imports.gi.GLib; const Gio = imports.gi.Gio; const Lang = imports.lang; @@ -95,23 +89,22 @@ don't use. const Params = imports.misc.params; const Tweener = imports.ui.tweener; const Util = imports.misc.util; - +``` The alphabetical ordering should be done independently of the location of the location. Never reference `imports` in actual code. -Constants ---------- +## Constants We use CONSTANTS_CASE to define constants. All constants should be directly under the imports: - +```javascript const MY_DBUS_INTERFACE = 'org.my.Interface'; +``` -Variable declaration --------------------- +## Variable declaration Always use either `const` or `let` when defining a variable. - +```javascript // Iterating over an array for (let i = 0; i < arr.length; ++i) { let item = arr[i]; @@ -121,17 +114,17 @@ Always use either `const` or `let` when defining a variable. for (let prop in someobj) { ... } +``` If you use "var" then the variable is added to function scope, not block scope. See [What's new in JavaScript 1.7](https://developer.mozilla.org/en/JavaScript/New_in_JavaScript/1.7#Block_scope_with_let_%28Merge_into_let_Statement%29) -Classes -------- +## Classes There are many approaches to classes in JavaScript. We use our own class framework (sigh), which is built in gjs. The advantage is that it supports inheriting from GObjects, although this feature isn't used very often in the Shell itself. - +```javascript var IconLabelMenuItem = new Lang.Class({ Name: 'IconLabelMenuItem', Extends: PopupMenu.PopupMenuBaseItem, @@ -146,6 +139,7 @@ GObjects, although this feature isn't used very often in the Shell itself. log("menu opened!"); } }); +``` * 'Name' is required. 'Extends' is optional. If you leave it out, you will automatically inherit from Object. @@ -162,13 +156,12 @@ GObjects, although this feature isn't used very often in the Shell itself. still a giant function call, even though it may resemble a more conventional syntax. -GObject Introspection ---------------------- +## GObject Introspection GObject Introspection is a powerful feature that allows us to have native bindings for almost any library built around GObject. If a library requires you to inherit from a type to use it, you can do so: - +```javascript var MyClutterActor = new Lang.Class({ Name: 'MyClutterActor', Extends: Clutter.Actor, @@ -188,9 +181,9 @@ you to inherit from a type to use it, you can do so: alloc.x2, alloc.y2); } }); +``` -Translatable strings, `environment.js` --------------------------------------- +## Translatable strings, `environment.js` We use gettext to translate the GNOME Shell into all the languages that GNOME supports. The `gettext` function is aliased globally as `_`, you do not need to @@ -204,8 +197,7 @@ and "double quotes" for strings that the user may see. This allows us to quickly find untranslated or mistranslated strings by grepping through the sources for double quotes without a gettext call around them. -`actor` and `_delegate` ------------------------ +## `actor` and `_delegate` gjs allows us to set so-called "expando properties" on introspected objects, allowing us to treat them like any other. Because the Shell was built before @@ -214,7 +206,7 @@ that has a property called `actor`. We call this wrapper class the "delegate". We sometimes use expando properties to set a property called `_delegate` on the actor itself: - +```javascript var MyClass = new Lang.Class({ Name: 'MyClass', @@ -229,6 +221,7 @@ the actor itself: actor.set_label("You clicked the button!"); } }); +``` The 'delegate' property is important for anything which trying to get the delegate object from an associated actor. For instance, the drag and drop @@ -236,16 +229,14 @@ system calls the `handleDragOver` function on the delegate of a "drop target" when the user drags an item over it. If you do not set the `_delegate` property, your actor will not be able to be dropped onto. -Functional style ----------------- +## Functional style JavaScript Array objects offer a lot of common functional programming capabilities such as forEach, map, filter and so on. You can use these when they make sense, but please don't have a spaghetti mess of function programming messed in a procedural style. Use your best judgment. -Closures --------- +## Closures `this` will not be captured in a closure, it is relative to how the closure is invoked, not to the value of this where the closure is created, because "this" @@ -254,15 +245,16 @@ variable that can be captured in closures. All closures should be wrapped with Function.prototype.bind or use arrow notation. - +```javascript const Lang = imports.lang; let closure1 = () => { this._fnorbate(); }; let closure2 = this._fnorbate.bind(this); +``` A more realistic example would be connecting to a signal on a method of a prototype: - +```javascript const Lang = imports.lang; const FnorbLib = imports.fborbLib; @@ -276,19 +268,21 @@ prototype: this._updateFnorb(); } }); +``` -Object literal syntax ---------------------- +## Object literal syntax In JavaScript, these are equivalent: - +```javascript foo = { 'bar': 42 }; foo = { bar: 42 }; +``` and so are these: - +```javascript var b = foo['bar']; var b = foo.bar; +``` If your usage of an object is like an object, then you're defining "member variables." For member variables, use the no-quotes no-brackets syntax: `{ bar: @@ -298,14 +292,13 @@ If your usage of an object is like a hash table (and thus conceptually the keys can have special chars in them), don't use quotes, but use brackets: `{ bar: 42 }`, `foo['bar']`. -Getters, setters, and Tweener ------------------------------ +## Getters, setters, and Tweener Getters and setters should be used when you are dealing with an API that is designed around setting properties, like Tweener. If you want to animate an arbitrary property, create a getter and setter, and use Tweener to animate the property. - +```javascript var ANIMATION_TIME = 2000; var MyClass = new Lang.Class({ @@ -331,3 +324,4 @@ property. { position: 100, time: ANIMATION_TIME, transition: 'easeOutQuad' }); +``` diff --git a/README b/README.md similarity index 62% rename from README rename to README.md index 0bfcf5c09..6bec164c4 100644 --- a/README +++ b/README.md @@ -1,3 +1,4 @@ +# GNOME Shell GNOME Shell provides core user interface functions for the GNOME 3 desktop, like switching to windows and launching applications. GNOME Shell takes advantage of the capabilities of modern graphics hardware and introduces @@ -6,15 +7,14 @@ easy to use experience. For more information about GNOME Shell, including instructions on how to build GNOME Shell from source and how to get involved with the project, -see: +see the [project wiki][wiki] - https://wiki.gnome.org/Projects/GnomeShell +Bugs should be reported to the GNOME [bug tracking system][bug-tracker]. -Bugs should be reported at http://bugzilla.gnome.org against the 'gnome-shell' -product. - -License -======= +## License GNOME Shell is distributed under the terms of the GNU General Public License, -version 2 or later. See the COPYING file for details. +version 2 or later. See the [COPYING][license] file for details. +[project-wiki]: https://wiki.gnome.org/Projects/GnomeShell +[bug-tracker]: https://gitlab.gnome.org/GNOME/gnome-shell/issues +[license]: COPYING diff --git a/browser-plugin/README b/browser-plugin/README.md similarity index 82% rename from browser-plugin/README rename to browser-plugin/README.md index 9eccb7ca3..8952e2bf3 100644 --- a/browser-plugin/README +++ b/browser-plugin/README.md @@ -4,14 +4,14 @@ the extensions repository to provide good integration, letting the website know which extensions are enabled and disabled, and allowing the website to enable, disable and install them. -Bugs should be reported at http://bugzilla.gnome.org against the 'gnome-shell' -product. +Bugs should be reported to the GNOME [bug tracking system][bug-tracker]. -License -======= +## License The GNOME Shell Browser Plugin, like GNOME Shell itself is distributed under the GNU General Public License, version 2 or later. The plugin also contains header files from the "NPAPI SDK" project, tri-licensed under MPL 1.1, GPL 2.0 and LGPL 2.1. These headers are third-party sources and can be retrieved from: http://code.google.com/p/npapi-sdk/ + +[bug-tracker]: https://gitlab.gnome.org/GNOME/gnome-shell/issues diff --git a/data/theme/README b/data/theme/README deleted file mode 100644 index 688892dba..000000000 --- a/data/theme/README +++ /dev/null @@ -1,31 +0,0 @@ -Summary -------- - -* Do not edit the CSS directly, edit the source SCSS files and the CSS files will be generated - automatically when building with meson + ninja and left inside the build directory to be - incorporated into the gresource XML (you'll need to have sassc installed). - -How to tweak the theme ----------------------- - -Adwaita is a complex theme, so to keep it maintainable it's written and processed in SASS, the -generated CSS is then transformed into a gresource file during gtk build and used at runtime in a -non-legible or editable form. - -It is very likely your change will happen in the _common.scss file. That's where all the widget -selectors are defined. Here's a rundown of the "supporting" stylesheets, that are unlikely to be the -right place for a drive by stylesheet fix: - -_colors.scss - global color definitions. We keep the number of defined colors to a necessary minimum, - most colors are derived from a handful of basics. It is an exact copy of the gtk+ - counterpart. Light theme is used for the classic theme and dark is for GNOME3 shell - default. - -_drawing.scss - drawing helper mixings/functions to allow easier definition of widget drawing under - specific context. This is why Adwaita isn't 15000 LOC. - -_common.scss - actual definitions of style for each widget. This is where you are likely to add/remove - your changes. - -You can read about SASS at http://sass-lang.com/documentation/. Once you make your changes to the -_common.scss file, you can run ninja to generate the final CSS files. diff --git a/data/theme/README.md b/data/theme/README.md new file mode 100644 index 000000000..192dc65e4 --- /dev/null +++ b/data/theme/README.md @@ -0,0 +1,32 @@ +## Summary + +Do not edit the CSS directly, edit the source SCSS files and the CSS files +will be generated automatically when building with meson + ninja and left +inside the build directory to be incorporated into the gresource XML (you'll +need to have sassc installed). + +## How to tweak the theme + +Adwaita is a complex theme, so to keep it maintainable it's written and +processed in SASS, the generated CSS is then transformed into a gresource +file during gtk build and used at runtime in a non-legible or editable form. + +It is very likely your change will happen in the [_common.scss][common] file. +That's where all the widget selectors are defined. Here's a rundown of +the "supporting" stylesheets, that are unlikely to be the right place +for a drive by stylesheet fix: + +| File | Description | +| ------------------------ | ----------------- | +| [_colors.scss][colors] | global color definitions. We keep the number of defined colors to a necessary minimum, most colors are derived from a handful of basics. It is an exact copy of the gtk+ counterpart. Light theme is used for the classic theme and dark is for GNOME3 shell default. | +| [_drawing.scss][drawing] | drawing helper mixings/functions to allow easier definition of widget drawing under specific context. This is why Adwaita isn't 15000 LOC. | +| [_common.scss][common] | actual definitions of style for each widget. This is where you are likely to add/remove your changes. | + +You can read about SASS on its [web page][sass-web]. Once you make your +changes to the [_common.scss][common] file, you can run ninja to generate the +final CSS files. + +[common]: data/theme/gnome-shell-sass/_common.scss +[colors]: data/theme/gnome-shell-sass/_colors.scss +[drawing]: data/theme/gnome-shell-sass/_drawing.scss +[sass-web]: http://sass-lang.com/documentation/ diff --git a/data/theme/gnome-shell-sass/README b/data/theme/gnome-shell-sass/README deleted file mode 100644 index 7f2a257e8..000000000 --- a/data/theme/gnome-shell-sass/README +++ /dev/null @@ -1,7 +0,0 @@ -GNOME Shell Sass is a project intended to allow the sharing of the theme sources in sass between gnome-shell and other projects like gnome-shell-extensions. - -License -======= -GNOME Shell Sass is distributed under the terms of the GNU General Public License, -version 2 or later. See the COPYING file for details. - diff --git a/data/theme/gnome-shell-sass/README.md b/data/theme/gnome-shell-sass/README.md new file mode 100644 index 000000000..7d6090ffe --- /dev/null +++ b/data/theme/gnome-shell-sass/README.md @@ -0,0 +1,10 @@ +# GNOME Shell Sass +GNOME Shell Sass is a project intended to allow the sharing of the +theme sources in sass between gnome-shell and other projects like +gnome-shell-extensions. + +## License +GNOME Shell Sass is distributed under the terms of the GNU General Public +License, version 2 or later. See the [COPYING][license] file for details. + +[license]: COPYING