Newbie Guide for People Patching Styles

How Do I File a New Bug?

• In Bugzilla, click on New. Select Dreamwidth Development. In Component, select Style System. Enter a Summary and a Description. Mention style and author(s) in the summary. If you're patching a color theme, add author names and submission URLs to the description. If you're patching a style, mention the style name, the number of themes it has, the name of the default theme, the author's name and the submission URL.

• Click on Show Advanced Fields. Set Initial State to ASSIGNED and enter your Bugzilla e-mail address in Assign To.

Where Are Style Files?

• core2.s2 is in ~/dw/cvs/dw-free/bin/upgrading/s2layers/

• Theme and layout .s2 files are in ~/dw/cvs/dw-free/bin/upgrading/s2layers/STYLENAME/ or ~/dw/cvs/dw-nonfree/bin/upgrading/s2layers/STYLENAME/

• .pm style files are in ~/dw/cvs/dw-free/cgi-bin/LJ/S2Theme/ or ~/dw/cvs/dw-nonfree/bin/upgrading/s2layers/LAYERNAME/

• S2Theme.pm is in ~/dw/cvs/dw-free/cgi-bin/LJ/

• S2Theme_local.pm is in ~/dw/cvs/dw-nonfree/cgi-bin/LJ/

• s2layers.dat is in ~/dw/cvs/dw-free/bin/upgrading/

• s2layers-local.dat is in ~/dw/cvs/dw-nonfree/bin/upgrading/

Dw-free or dw-nonfree?

• To be usable on the site, third party images must be obtained from a site which explicitly allows storage on one's own server, commercial use, and use in website templates, or the designer must have acquired a written permission from the image owner and included it in their Contributor Licensing Agreement. If this isn't the case, images must be replaced or removed from the style/theme.

• Styles go to dw-nonfree if Dreamwidth can use them but can't redistribute/sublicense them.

• Themes go to local files in dw-nonfree if they contain images Dreamwidth can use but can't redistribute/sublicense.

• Themes go to local files in dw-nonfree if the base style is already in dw-nonfree. This the case for Transmogrified and Sunday Morning themes.

Adding a New Style

Edit s2layers.dat

• If the style goes to dw-nonfree, edit s2layers-local.dat instead.

• If this is a new Core2 layout, add:

stylename/layout          layout          core2
stylename/themes          theme+          stylename/layout

• If this is a child of Tabula Rasa, add:

stylename/layout          layout(core2base/layout)    core2
stylename/themes          theme+                      stylename/layout

Edit S2Theme.pm

• If the default theme goes to dw-nonfree, edit S2Theme_local.pm instead.

• Scroll down to %default_themes and add the style and default theme:

layoutname => 'stylename/defaulttheme',

Create STYLENAME.pm

• Create STYLENAME.pm in ~/dw/cvs/dw-free/cgi-bin/LJ/S2Theme/ or ~/dw/cvs/dw-nonfree/cgi-bin/LJ/S2Theme/.

• Add:

package LJ::S2Theme::layoutname;
use base qw( LJ::S2Theme );
use strict;
 
sub layouts { ( "1" => "one-column", "2l" => "two-columns-left", "2r" => "two-columns-right", "3" => "three-columns-sides", "3r" => "three-columns-right", "3l" => "three-columns-left" ) }
sub layout_prop { "layout_type" }
 
1;

Remove layout options that don't apply to the style, of course.

Create the STYLENAME directory

• Create a directory with the name of the style in ~/dw/cvs/dw-free/bin/upgrading/s2layers/ or ~/dw/cvs/dw-nonfree/bin/upgrading/s2layers/.

Create layout.s2

• In the directory you've created, create a file named layout.s2. Add:

layerinfo type = "layout";
layerinfo name = "layoutname";
layerinfo redist_uniq = "layoutname/layout";
layerinfo author_name = "someuser";
layerinfo lang = "en";
 
set layout_authors = [ { "name" => "someuser", "type" => "user" } ];

• Make sure to respect the designer's wishes concerning capitalization and that layerinfo author_name and layout_authors match.

• If the designer doesn't want their name to be displayed as a username, use this instead:

set layout_authors = [ { "name" => "someuser" } ];

• If there are resources to credit, add them:

set layout_resources = [ { "name" => "Name", "url" => "http://URL" } ];

• Add the style code.

• If the style has custom properties, they should be sorted into existing groups (presentation, colors, fonts, images, modules, text, other) by appending _child to the group name. For example:

propgroup images_child
    property string image_module_list { des = "Module list image"; }

• If a module has more or fewer available positions than other modules, you can customize the sections it can be set to by using _override. For example:

    property string module_navlinks_section_override {
        values = "none|(none)|header|Header|one|Group One|two|Group Two";
        grouped = 1;
        }
 
set grouped_property_override = { "module_navlinks_section" => "module_navlinks_section_override" };
 
set module_navlinks_section = "header";

Of course, you need to make sure it's printed correctly when set to every position, possibly by editing function Page::print() { }.

Check layout.s2

• No tabs or trailing spaces.

• No empty properties (S2 or CSS).

• No hardcoded colors, fonts or text except shadows or :before/:after characters.

• No redundant code (S2 or CSS).

• Format CSS to be easily readable and editable. Selectors should be listed in the order they're displayed on the screen, divided into sections thanks to comments, properly indented and spaced out; properties should be listed alphabetically:

/* Modules
***************************************************************************/
 
.entry, .comment {
    margin: 2em .5em;
    padding: 2em;
    }

• Remove leading zeros from decimals (.5em instead of 0.5em).

• Format CSS to use shorthand whenever possible:

    border: 1px solid $*color_module_border;
    border-top: none;
    list-style: square inside url($*image_list_bullet);
    margin: 2em .5em 1em;

instead of:

    border-bottom: 1px solid $*color_module_border;
    border-left: 1px solid $*color_module_border;
    border-right: 1px solid $*color_module_border;
    list-style-image: url($*image_list_bullet);
    list-style-position: inside;
    list-style-type: square;
    margin-bottom: 1em;
    margin-left: .5em;
    margin-right: .5em;
    margin-top: 2em;

• Group selectors whenever possible.

Create themes.s2

• In the directory you've created, create a file named themes.s2.

• If some themes go to dw-nonfree, create themes-local.s2 in dw-nonfree as well.

• Follow the steps outlined in the next section.

Adding a New Color Theme

Edit themes.s2

• If the theme goes to dw-nonfree, edit themes-local.s2 instead.

• Make sure the color theme has the right header. As Afuna explained here in dw_dev_training, it should look like this:

#NEWLAYER: layoutname/themename
layerinfo type = "theme";
layerinfo name = "Theme Name";
layerinfo redist_uniq = "layoutname/themename";
layerinfo author_name = "someuser";

• If the color theme author is not the style author, add this this line below, separated by a blank line:

set theme_authors = [ { "name" => "someuser", "type" => "user" } ];

• Make sure to respect the designer's wishes concerning capitalization and that layerinfo author_name and theme_authors match..

• If the designer doesn't want their name to be displayed as a username, use this instead:

set theme_authors = [ { "name" => "someuser" } ];

• If there are resources to credit, add them:

set layout_resources = [ { "name" => "Name", "url" => "http://URL" } ];

If there were already resources credited in the style, don't forget to add them again.

• If the theme has any images, name them like this: themename_imagename.xxx. Keep the image name used in other themes if there are any.

If there's only one image, give it the theme name: themename.xxx

If the theme has generic images used in other themes, simply use imagename.xxx.

In the theme, use layoutname/themename_imagename.xxx, layoutname/themename.xxx or layoutname/imagename.xxx as the URL.

• If you need to add theme-specific CSS, use:

function Page::print_theme_stylesheet() {
    """
    CSS HERE
    """;
}

• Make sure to add the theme code in the right place: themes should be alphabetically sorted.

Check your theme file

• No tabs or trailing spaces.

• No empty properties (S2 or CSS).

• No hardcoded colors in print_theme_stylesheet() if possible.

• Use shorthand for color codes whenever possible (#555 instead of #555555; #abc instead of #aabbcc).

• Sort properties into categories. Possible categories are: Presentation, Page Colors, Entry Colors, Module Colors, Images and Fonts. Use these headers to separate each category:

##===============================
## Page Colors
##===============================

• Properties should be sorted alphabetically into each category, but sometimes logic should prevail. For example, generic properties such as color_page_background go before specific properties such as before color_header_background.

• Format CSS to be easily readable and editable: use indents and spaces, list properties alphabetically, use shorthand whenever possible.

• Each theme file must be separated by two blank lines. Leave one blank line after the last theme in the file.

• If you see another theme which needs editing, do it in another patch.

Adding New Files to your Patch

• Type hg addremove if this patch adds or delete files then hg refresh.

• If you're adding images, don't forget to zip them, attach them to your bug and set them to review ? and commit ?.

Test, Test and Test

• In Customize, make sure everything is correctly listed and named. For styles, also make sure you can select the page layouts working with your style, and customize your style.

• On your test account, check colors on all pages. Don't forget visited links, bottom links on comment pages and comment subjects. For styles, also make sure all types of layouts, all pages, all sorts of entries and comments are displayed correctly and do so in various screen resolutions and font sizes. Don't forget to check community journals too.

Preview Pictures

• To make preview pictures, you need to take a screenshot of the Recent Pages of your test account. This account needs to have two or three dummy entries with dummy titles and a Dreamwidth icon, and generally few sidebar modules and no footer modules. Lorem Ipsum generators and screenshot extensions may help you with that.

• It is best if you take your screenshot when your screen is set to a size of 1280x800 pixels as this is the most common resolution used by Dreamwidth users. A good font size is between 14 pixels and 16 pixels.

• Screenshots must then be resized to 150x114 pixels. If doing so distorts the image, you need to edit the original screenshot in a photo editor program, edit entries, or add/remove modules until your screenshot can be resized without any distortion.

• If you can't do preview pictures mention it so that someone can do them for you. You can also ask for help at dreamscapes.

• A few tips:

It might be a good idea to create accounts specifically for making previews --one per style-- so that you don't lose your set-up.

If you have a program with scripting functions, you can use them to automate resizing and saving.