Ethical Digital Standards Site

This is the main source repository of the Barcelona Ethical Digital Standards initiative by the Barcelona City Hall. This repo provides the means to generate the website of the initiative. The resultant site can be found at www.barcelona.cat/digitalstandards.

The site contains a number of documents defining an open source Policy Toolkit for cities to develop digital policies that put citizens at the center and make Governments more open, transparent, and collaborative.

The site is generated with the static site generator Antora. Antora takes a set of documentation components written in AsciiDoc and stored in a number of Git repositores, and combines them in a unified website.

In Antora the site’s user interface (UI) and theme is maintained separately (in a different repository) from the content. All the important repositories for our site are listed in section Repositories involved in the generation of the site.

Table of Contents

• Forking and contributing
• Repositories involved in the generation of the site
• Deploy the site
• Test the site running Antora locally
  • Generate the site from locally cloned document repositories
• Edit some document and re-publish
  • On-line edition vs. local editor
  • Create a new documentation page
  • Write AsciiDoc
• Add a document to the site
  • (Step 1) Import the repository template for new documents
  • (Step 2) Protect the master branch and add explicit permissions to it
  • (Step 3) Add a short description to the repository
  • (Step 4) Add topics (labels) to the repository
  • (Step 5) Configure other repository options
  • (Step 6) Set up the Antora document configuration file
  • (Step 7) Fill-up the metadata for the document
  • (Step 8) Create the content for the document
  • (Step 9) (If lang is not EN) Take care of English-bias of the template
  • (Step 10) (Optional) Convert contents from another format to AsciiDoc
  • (Step 11) Update navigation information
  • (Step 12) Set up things for PDF generation
  • (Step 13) Add the document to the site repository
• Generate PDF files for the documents
• Modify the UI

Forking and contributing

The site generated from this repository and the documents it contains can be forked, adapted, and reused. The documents and the landing page are distributed under the conditions of the Creative Commons Attribution-ShareAlike 4.0 International (CC-BY-SA-4.0) license. The code for the UI has a Mozilla Public License 2.0 (MPL-2.0).

We—​the maintainers of this project and the City of Barcelona—​value your input, enjoy feedback and welcome improvements to our free software projects and documentation. For more details see the CONTRIBUTING file at the root of this repository.

Repositories involved in the generation of the site

A number of Git repositories are involved in the generation of the site:

• This (the main) repository. It contains:

  • The so-called Antora’s playbook file: site.yml. It contains a list of all the repositories containing documentation, the location of the UI (see below), the name and URL for the site, and other configuration.

  • The landing page for the site. There is an Antora component for each language (CA, EN, ES) in folders landing-page-{lang}.

  • Configuration for deployment with Netlify.

• The UI repo. An Antora UI is a repository containing all the presentation elements for the site (templates to generate HTML from AsciiDoc files, CSS, icons, and JavaScript snippets). Our UI can be found at github.com/AjuntamentdeBarcelona/ethical-digital-standards-ui.

• Documentation repos. Every repository contains a different Antora component, and every component has a document in one of the supported languages.

  • github.com/AjuntamentDeBarcelona/agile-methodologies-bcn-en

  • github.com/AjuntamentdeBarcelona/digital-service-standards-bcn-ca

  • github.com/AjuntamentdeBarcelona/digital-service-standards-bcn-en

  • github.com/AjuntamentdeBarcelona/digital-service-standards-bcn-es

  • github.com/AjuntamentDeBarcelona/ethical-data-management-bcn-en

  • github.com/AjuntamentDeBarcelona/free-software-guidelines-bcn-en

  • github.com/AjuntamentDeBarcelona/ict-procurement-bcn-ca

  • github.com/AjuntamentDeBarcelona/ict-procurement-bcn-en

  • github.com/AjuntamentDeBarcelona/innovative-procurement-bcn-en

  • github.com/AjuntamentDeBarcelona/tech-practices-code-bcn-ca

  • github.com/AjuntamentDeBarcelona/tech-practices-code-bcn-en

  • github.com/AjuntamentDeBarcelona/tech-sovereignty-guide-bcn-ca

  • github.com/AjuntamentDeBarcelona/tech-sovereignty-guide-bcn-en

  • github.com/AjuntamentDeBarcelona/tech-sovereignty-guide-bcn-es

  • github.com/AjuntamentDeBarcelona/tech-sovereignty-manifesto-bcn-en

• Special documentation repos containing a general Glossary in every language:

  Note	Explain glossary.

  • github.com/AjuntamentDeBarcelona/eds-glossary-bcn-ca

  • github.com/AjuntamentDeBarcelona/eds-glossary-bcn-en

  • github.com/AjuntamentDeBarcelona/eds-glossary-bcn-es

Deploy the site

The site is automatically built and deployed by Netlify whenever a push is run on branch master of the present repository.

Important

If you change an existing document, those changes are not automatically deployed and you need to fire a manual deploy from Netlify.

If you want to test some change (in the documents or in the configuration), use a Pull Request. Every Pull Request in this or another repository is automatically followed (can take some time) by a testing deploy you can use to check that everything is OK.

Test the site running Antora locally

You will need this for developing and debugging.

In the simplest case, to build the site locally you only need to install Antora and clone this repository. From the root of the repo, run:

antora --stacktrace --pull --html-url-extension-style=indexify site.yml

This is the same command that Netlify runs during deploy.

Antora, following the playbook in site.yml, will clone all the repositories containing documentation, and also download a file called ui-bundle.zip containing the UI. The static site is generated under folder build/site/digitalstandards/ and can be browsed locally.

Note	TODO: either explain broken links and redirection workaround or fix them.

Generate the site from locally cloned document repositories

If instead of using content in online repositories you want to generate the site from locally cloned document repositories, you need to populate the workspace folder.

Change to workspace and clone there all the repositories in section Repositories involved in the generation of the site. Then run the same command above but using file site-local.yml instead of site.yml.

Note	The configuration in site-local.yml uses Antora’s Author Mode to render whatever version of the documents is in your working trees, instead of using a Git tag or branch as a reference.

Edit some document and re-publish

Changes to the contents of the documents need to be applied to the master branch of the corresponding repository.

Then, the only thing you need to do to see the changes published is redeploy the site using Netlify.

On-line edition vs. local editor

Note

TODO.

Create a new documentation page

Note	TODO. See docs.decidim.org/docs-authoring/en/authoring/#create-page.

Write AsciiDoc

Note

TODO.

Add a document to the site

Every (translation of a) document requires the creation of a new repository in the City Council space at GitHub.

The steps to get the new repository are described in the following sections.

(Step 1) Import the repository template for new documents

Note	Importing a repository is a different concept from forking or creating an empty one.

Go to the ＋ ▾ drop down menu on GitHub’s top bar (on the right) and select the Import repository option.

We have a repository with a template for new documents.

1. Input github.com/gmarpons/eds-new-document-template as the repository to clone (i.e. import from).

2. Select AjuntamentDeBarcelona organization as the owner of the repository, if you have other options. If this option does not appear, you probably do not have the needed permissions.

3. Choose a name for your new repository following the examples in section Repositories involved in the generation of the site. In particular, follow the -bcn-{LANG} convention, and use the same names (in English) for different translations of the same document, only changing the language suffix.

4. Press the Begin import button.

The import can take some seconds or minutes.

In contrast with a GitHub fork, a repository import does not keep any link to the original repository (in this case, the template).

Our new repository template defines the basic file structure to facilitate:

• The online publication of the document.

• Filling up all the important metadata.

(Step 2) Protect the master branch and add explicit permissions to it

Go to Settings › Branches. Under "Branch protection rules", choose branch master.

Select options "Protect this branch" and "Restrict who can push to this branch", and deselect all other options. In section "People and teams with push access" add all the GitHub users you want to have write permission to the master branch, for instance to accept Pull Requests. Add them as collaborators with "Write" permission in Settings › Collaborators & teams as well.

(Step 3) Add a short description to the repository

At the top of the Code panel you will see the following message: "No description, website, or topics provided." Press the Edit button on the right to change the description. Try to use one single sentence, at most two.

Note	TODO: more concrete guidelines here.

(Step 4) Add topics (labels) to the repository

There is also an "Add topics" option. Press it. Add at least the topic ethical-digital-standards.

Note	TODO: other topics?

(Step 5) Configure other repository options

Go to Settings › Options and disable "Wikis" and "Projects". As the Javascript contained in the repo is not deployed as part of the website and only used to build the static site, you can disable the option "Security alerts" as well. Leave the other options in its default configuration.

(Step 6) Set up the Antora document configuration file

After importing, your document repository contains a file called antora.yml. It is a YAML file following the syntax property: value. You have to fill up the different declared properties following the instructions given in the same file.

Note	Do not confuse this file with the site’s Antora playbook, stored in the present repository.

(Step 7) Fill-up the metadata for the document

In the root of the new repo there is a file README.adoc. Fill-up the metadata there, and copy the result to ./modules/ROOT/partials/README.adoc in the same repository.

Note	TODO: explain metadata. See docs.decidim.org/docs-authoring/en/authoring/#fill-up-metadata.

(Step 8) Create the content for the document

Textual content is placed in ./modules/ROOT/pages and images in ./modules/ROOT/assets/images.

Every content we want to show as a single page (e.g. a section of your document) is going to be put in a separate .adoc (AsciiDoc) file. The template contains as example a file ./modules/ROOT/pages/rename-me.adoc that you need to rename to something significant, e.g., introduction.adoc.

For creating new content pages, follow instructions in section Create a new documentation page.

Single page documents

Put the contents in index.adoc.

Note

TODO.

(Step 9) (If lang is not EN) Take care of English-bias of the template

Note

TODO.

(Step 10) (Optional) Convert contents from another format to AsciiDoc

If the contents for your document already exist in a different format, you can follow indications in docs.decidim.org/docs-authoring/en/administration/#conversion.

(Step 11) Update navigation information

The template contains a file ./modules/ROOT/nav.adoc.

It can contain references to any files or sections in the documents, as explained in Antora docuementation. Its items and sub-items are used to present a navigation menu for the document (you can think of it as a table of contents).

Add a reference for every page in modules/ROOT/pages

Example 1. Reference from nav.adoc

If your file is named modules/ROOT/pages/introduction-to-free-software.adoc, add a line

* xref:introduction-to-free-software.adoc[Introduction to Free Software]

To nav.adoc.

The text between brackets is what will be shown in the navigation menu.

(Step 12) Set up things for PDF generation

Note

TODO.

(Step 13) Add the document to the site repository

Here you need to change the site repository, i.e., this very same repository, github.com/AjuntamentdeBarcelona/ethical-digital-standards-site.

To follow a proper Git workflow:

1. Make your own GitHub fork of the site repository. Work with your copy in the following numbered items. (Another possibility is to create a temporary branch in the main repository).

2. Edit files site.yml and site-local.yml to add the new document under the content section (repeatedly for every repository if the document has been translated to different languages). The syntax for the content section is described in the Antora Manual.

3. Edit files landing-page-{LANG}/modules/ROOT/nav.adoc and add a cross-reference (xref) to the first page of the new document (and other pages if needed).

   Note	TODO: see if the first page is always index.adoc. Explain language casuistic.

4. Add the new repositories location to section Repositories involved in the generation of the site in this README file.

5. Commit your changes and make a Pull Request (PR). If everything goes well you will receive an automatic comment to the PR with an URL for a preview. Use the preview to check that the site looks fine.

6. In case everything is OK, accept the PR and an automatic deploy (publishing) will follow.

Generate PDF files for the documents

Note

TODO.

Modify the UI

If you need to change the UI (theme, presentation and interaction aspects) of the site, you’ll find instructions in the site’s UI project repository.