readme.md 6.27 KB
Newer Older
1
# Better Themes
Aral Balkan's avatar
Aral Balkan committed
2

Aral Balkan's avatar
Aral Balkan committed
3
These are the themes used by the Better Builder while generating the data for the site.
Aral Balkan's avatar
Aral Balkan committed
4 5 6 7 8

Files in the `/common` folder are used as a base when building for either environment. The `/site` and `/app` folders have specialised styles and templates that extend and override the ones in the `/common` folder.

## Structure

9
Pages are created based on the contents of `page.html`, which might include other templates as partials.
Aral Balkan's avatar
Aral Balkan committed
10 11 12 13 14

## Assets

All files in the `/images`, `/styles`, `/scripts`, and `/fonts` folders are copied over to the same folders in the root directory of the generated data and will be accessible via those same URL fragments from the local server.

15 16 17 18 19 20
## Testing locally.

[Better Builder](https://source.ind.ie/better/builder) will automatically pick up your changes as you save and rebuild your local data.

## Saving your changes by pushing to production

21
If you have commit rights, you can push to production with:
22 23 24 25 26

```bash
./save
```

27
Or, to manually do what the *save* convenience script does:
28 29 30 31 32 33 34 35 36 37 38 39 40 41 42

```bash
git push live master
```

## Deployment

If you have commit rights to the content repository, just run the deployment script:

```bash
./deploy
```

This will create a tag (you will have to enter a tag mesage when prompted, describing the release) and push it to production. Please make sure that you have already committed your changes and pushed them to production either via `git push live master` or by running the `./save` script, which does the same thing.

Aral Balkan's avatar
Aral Balkan committed
43 44
## Contributing

45
**TL;DR:** Develop and test locally in your own branch (named with the URL of the [issue](https://source.ind.ie/blockdown/themes/issues) you are addressing; see below for details), or your own fork, and create a merge request once you’re ready to submit your changes.
Aral Balkan's avatar
Aral Balkan committed
46 47 48 49 50 51 52 53

#### A. Search for existing issues & discuss your proposed changes with the community

1. [Check the issues first](https://source.ind.ie/blockdown/themes/issues) to make sure that other people are not already working on similar functionality so you don’t duplicate work. You might be able to help out with an existing initiative.
2. [Open a new issue](https://source.ind.ie/blockdown/themes/issues) and discuss your proposed changes before commiting too much work into it. The community might have valuable input.

#### B. Develop locally

54
1. Make sure [Better Builder](https://source.ind.ie/blockdown/builder) is installed and running locally. The Better Builder installation will create a fully offline development and testing environment for you. (You can find your local Better installation at `~/ind.ie.blockdown.builder/` on your development machine.)
Aral Balkan's avatar
Aral Balkan committed
55
2. Create a local branch for your changes based on the URL of the issue ticket you opened (e.g., `git checkout -b "https://source.ind.ie/blockdown/themes/issues/2"). Branches not linked to issues will not be accepted for merge requests.
56
3. In your branch, make your changes and update the theme. (You can find the themes folder in your local Better installation at `~/ind.ie.blockdown.builder/themes` on your development machine.)
Aral Balkan's avatar
Aral Balkan committed
57 58 59 60

#### C. Test locally

1. Merge your changes into master
61 62
2. Push to the local development repository: `git push origin master` (Better Builder — see B1, above — will automatically pick up your changes and regenerate the content.)
3. Test out the result by running [the Better iOS app](https://source.ind.ie/blockdown/apps) in the iOS Simulator for the app theme and in the browser at [http://localhost:3000](http://localhost:3000) for the site theme.
Aral Balkan's avatar
Aral Balkan committed
63 64 65 66 67 68
4. If you’re not happy with the changes, go back to B.

#### D. Submit your changes

Once you’re happy with your changes, submit them to the project. Make sure your commit message closes the issue you opened (e.g., `git commit -am "Summary of changes. Closes #<issue-number>."`).

69 70 71 72 73 74 75 76 77
##### If you have commit rights:

	1. `./save` (or run `git push live master` which does the same thing)
	2. `./deploy` to create a new tag and push it to production, thereby triggering a rebuild of the Better data.

##### If you do *not* have commit rights:

	1. `git push live master` to push to your own fork
	2. Submit a merge request
Aral Balkan's avatar
Aral Balkan committed
78 79 80 81

Once your changes have been approved by someone with deployment privileges, they will be included in the next release.

Thank you in advance for your effort and for contributing to the Ind.ie community.
82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107

## Notes

### News items

When grouping multiple updates in one major update, make a list within the list item and title with a `group-name` class.

```html
<ul class='posts-list'>
    <li class='h-entry major-update'>
        <time class='dt-published' datetime='2016-07-07'>7th Jul, 2016</time>
        <h2 class='group-name'>Group Name</h2>
        <ul>
            <li>
                <h3 class='p-name'>Update Title #1</h3>
                <p class='p-summary'>Summary text.</li>
            <li>
                <h3 class='p-name'>Update Title #2</h3>
                <p class='p-summary'>Summary text.</p>
            </li>
            <li>
                <h3 class='p-name'>Update Title #3</h3>
                <p class='p-summary'>Summary text.</p>
            </li>
        </ul>
    </li>
108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166
```

## CSS formatting

```css

/*
 Tabs not spaces! (except inside comments, for legibility)
 One empty line between each group of rules
*/

brackets
{
    on their own line: like this;
}

    @media queries are indented below their matching element
    {
        element
        {
            like: this;
        }
    }

comma, separated, selectors, on, one, line
{
    like: this;
}

.rules-should-be-in-alphabetical-order
{
    background: #000;
    color: #fff;
    display: block;
}

```

## CSS comments

```css
/****************************************************************************
 *                      Sections are styled like this                       *
 ****************************************************************************/

/* ↓ comments on CSS rules are like this, on a separate line, above the rule itself */

/*
 comments on groups of CSS rules (and long comments) are like this, with the start and end on their own lines
*/

/********************
 *      Note        *
 ********************

 A special note about the CSS in this section is styled like this, so it doesn’t stand out as much as the section heading comments, and we don’t have to worry about formatting each line.

 *******************/
 ```