TechDocs/Mainpage/Editing/BestPractices

Best Practices for working with fsfe.org

Thanks to our community, there are many people working on our most beloved website. That is why it is important to follow a few best practices that may be a bit of extra mental work and time spent for you, but save a lot of nerves and effort for all the others. This page collects a few suggestions for how your contributions to the website can be most effective.

Thank you for following them! :)

Enable Git hooks

To prevent the biggest mistakes, please activate Git hooks on your local repository. They check for things like syntax, wrong file names, typos in tags and news dates and many more.

Read here on how to enable them.

No in-line CSS

For some special pages, you might want to change how certain aspects look like, e.g. the colour of a text or the display of a box.

In order to do so, please do not use in-line CSS, so style definitions inside of the file, like this:

<head>
  ...
  <style type=text/css">
    p {
      font-color: red;
    }
  </style>
</head>

or this:

<p>The text after this <span style="font-color: red;">is red</span></p>

This is bad practice because if some parts of the CSS change in the future, these manual edits may look completely awkward, and they are hard to maintain and improve.

Instead, you can do the following:

  1. Consider whether you actually really need a custom style. Perhaps it already exists (TODO: reference existing classes), or perhaps it's just not so important, and a unified look is more desired.
  2. If you think all occurences of a certain element, e.g. a blockquote, should be enhanced, do the edits directly inside of the respective files in look/, where all CSS rules live.

  3. If a new CSS class is needed, you can of course edit style.less or fsfe.less directly. However, it has proven to be more clear to add a separate file in look/elements/ or look/pages/ depending on the type of class you'd like to add. To include you new style file to the site-wide CSS, just add an include on top of fsfe.less.

  4. As always, ask the Web Team if you need help.

You surely know how to make links in the .xhtml or .xml files: <a href="https://example.com">link here</a>. This is perfectly fine for external sites.

However, for the own website, there is a more clever way. Imagine that we change our domain in the future, or that https:// will be superseded by foobar://: we'd have to change all those old occurences!

That is why you are encouraged to remove https://fsfe.org from all links. So if you want to link to our Free Software overview, just use <a href="/freesoftware/">Free Software overview</a>.

Please note that this does not work for other FSFE servers like https://wiki.fsfe.org. In these cases, you have to threat those links as completely external pages, even if they belong to the FSFE.

The FSFE's website language management system is well thought-out: it automatically detects the browser language, and uses translated content if there is one – and otherwise falls back to English. In order to make all of that work, you should not pre-define the language of the links to fsfe.org.

Bad examples:

Good examples:

TODO: define preference of: /order, /order/, /order/order.html, /order/index.html`

Format of source code

Our build system does not care much about superfluous blank lines or thousands of spaces and tabs that you spread around a source code file. But our human editors do.

Therefore, please try to follow a few best practices when editing files for fsfe.org:

Indent your code logically

HTML/XML is not the most user-friendly markup. You can make it easier for other editors if you make some kind of visible tree structure by indenting child elements, e.g. with 2 or 4 spaces. This may look like the following:

...
<body>
  <p>Here is the intro text, and now comes a list:</p>

  <ul>
    <li>first item</li>
    <li>last item</li>
  </ul>

  <figure>
    <img src="https://pics.fsfe.org/..." alt="image description" />
    <figcaption>
      This text describes the picture
    </figcaption>
  </figure>
</body>
...

This way, understanding the structure and level of the different elements is much easier. Please try to keep the indent width and style (tabs or spaces) unified in your file. A good text editor helps you with that.

By the way, indentation is also helpful for other files, e.g. CSS.

Wrap long lines

It's considered good practice to wrap long lines, e.g. after 80 characters, especially for text. So instead of this:

<p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa quis enim. Donec pede justo, fringilla vel, aliquet nec, vulputate eget, arcu. In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo. Nullam dictum felis eu pede mollis pretium. Integer tincidunt. Cras dapibus. Vivamus elementum semper nisi. Aenean vulputate eleifend tellus. Aenean leo ligula, porttitor eu, consequat vitae, eleifend ac, enim. Aliquam lorem ante, dapibus in, viverra quis, feugiat a.</p>

...do it like this:

<p>
  Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean
  commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus
  et magnis dis parturient montes, nascetur ridiculus mus. Donec quam
  felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla
  consequat massa quis enim. Donec pede justo, fringilla vel, aliquet
  nec, vulputate eget, arcu. In enim justo, rhoncus ut, imperdiet a,
  venenatis vitae, justo. Nullam dictum felis eu pede mollis pretium.
  Integer tincidunt. Cras dapibus. Vivamus elementum semper nisi.
  Aenean vulputate eleifend tellus. Aenean leo ligula, porttitor eu,
  consequat vitae, eleifend ac, enim. Aliquam lorem ante, dapibus in,
  viverra quis, feugiat a.
</p>

This has numerous advantages:

  1. Easier to read, especially on wide screens
  2. Changes between two versions are easier to spot. If one word changes, only one line with ~8 words will change, not with 100. That is easier to overview.
  3. Comments by proofreaders, either manual or on pull requests on git.fsfe.org, are easier to share. You can give concrete directions like "In line 42, you have a typo" – the less text in this line, the better.

Good text editor applications help you with automatically or manually wrapping text after a certain amount of characters.

Delete your branch after merge

A part of some Git workflows is to work with branches in which you can do your modifications without interfering with others.

But after you created a Git branch, started a pull request and merged it successfully, it is good practice to delete the branch. Otherwise, there is a jungle of old branches hanging around, which may also take up a lot of disk space.

If you merged your Pull Request via the web interface, you will be offered a big red button that allows you to delete the branch. Note that you will not delete the history of your changes, and you will still have the branch locally on your computer if you ever have to restore it. So there's not much that can go wrong.

TechDocs/Mainpage/Editing/BestPractices (last edited 2020-09-28 09:27:58 by max.mehl)