- Working with the website source
- Coordination tools
- Responsible handling of write access
- Advanced information
Working with the website source
Getting access to the web pages
To have access to these tools, just follow these instructions:
If you are a supporter of the FSFE you already have read access to Git, just log in with your usual Fellowship username and password.
Everyone else can join the FSFE as a volunteer to get access to our Git and other services. For this, you will need to be subscribed to the web mailing list. Send an introduction of yourself to the list and one of our coordinators will be in touch to help you setup an account. More information about volunteer accounts and the necessary procedures can be found on this dedicated wiki page.
To have write access to the Git repository just write to email@example.com
Working with Git
You should be familiar with Git, and you should have an account on git.fsfe.org. For documentation on how to use Git, you can check out TechDocs/Git. The workflow for working with fsfe-website is documented in TechDocs/Git/Workflow. Read it carefully. If you do not understand any of the steps, please ask a technically inclined person or the Web Team and ask them to improve the Wiki page afterwards, so that others will not run into the same problem again.
Enabling Git hooks
We strongly recommend to enable some security measurements in the form of Git hooks. These are scripts that are called on your computer, e.g. when making a commit. Currently, the following client-side checks are available:
- Validate XML syntax so you don't upload files that contain errors
Display a warning if you cause previously up-to-date translations to become outdated (see here)
- Display a warning if you added a new tag for news and events that has not been used anywhere else so far
To activate these checks, run this command from the root directory (i.e. first level) of the fsfe-website repository (or the fork you cloned):
ln -sr tools/githooks/* .git/hooks/
If you see an error that the hook files (pre-commit and pre-receive at the time of writing) already exist, please check whether they are the same as the ones in tools/githooks/. If not, please take care of merging them together.
Please note that you have to have the xmllint command available which is provided by installing the packages libxml2-utils (e.g. Debian) or libxml2 (e.g. Arch Linux, Fedora) on your computer.
If some file has a wrong syntax, it throws an error and you can fix the problem. This way you don't have to be afraid to break anything with your contributions.
The work on the website pages is coordinated on the Webmasters mailing list.
In the fsfe-website repository's web interface you can find an issue tracker and the commit log.
The web team's wiki page may contain some further information about the webmasters' workflow.
If you want to keep track with all commits that are done to the web page sources, you can also subscribe to the commit notification mailing list and you will get a mail for every change posted to the source tree.
Responsible handling of write access
If you have write access to the web pages, please subscribe to the Webmasters mailing list.
Please bear in mind that all your changes will become effective and visible automatically, without any further action of anybody. Consequently, there are a few things we would request you to do whenever you commit changes or new files:
- The FSFE is held responsible for the content of the web pages. Please do not commit modifications that change the meaning of the text without approval from a core team member of the FSFE. (This is not necessary for translations of already existing content.)
If you are posting translations, and there is any chance that others can proofread it, use that chance. You can use the Translators mailing list to ask for proofreading (more information about our translators). Whether you are translating files or proofreading them, you are encouraged to spell-check files using some automated tools, such as GNU aspell, ispell, or your favourite spell-checker.
Make sure that all files are proper XML. By default, the Git server will check the XML syntax of files with .xml and .xhtml extensions, and will forbid the commit if XML errors are found. To avoid this, you can check your files before committing them by installing xmllint on your computer (available in Debian GNU/Linux distributions via the libxml2-utils package). You can run xmllint --noout file.en.xhtml to check a file – if the output is empty the file's syntax is correct.
Make sure the encoding of the file is consistent with the content of the "encoding" attribute declared in the first line of the file. For example, if your file is encoded as "UTF-8" , the first line of the file should read <?xml version="1.0" encoding="UTF-8" ?>.
Please coordinate with other people who also have Git write access to make sure that translations and fixes contributed by people without commit access are committed properly after they have been proofread. Of course, please check these files before you push them like you check your own files.
If you don't have an account on git.fsfe.org and just want to have a copy of the websites' sources on your computer, or if you cannot use the SSH link for any reason, you can also clone via the HTTPS clone link:
git clone https://git.fsfe.org/FSFE/fsfe-website.git
But if you want to edit the website source we encourage you to use the SSH clone link starting with firstname.lastname@example.org. Otherwise you will have to type in your Fellowship account credentials every time you push a change.
The test branch
The Git repository has two main code bases for the FSFE website, the master, which is used to build the production instance of the website at fsfe.org, and the test branch, which is used to build test.fsfe.org.
To work on major changes to the website, including debugging new features that could potentially break the site, you are encouraged to check out the test branch of the Git repository: git checkout test
In order to make changes to the test page, make them inside the test branch and push them to is upstream location:
git push upstream test
Checking out Pull Requests
For some reasons, e.g. previewing someone else's changes locally, you can check out Git Pull Requests.
To enable this, you will have to tell your git to fetch remote pull requests. Please open a terminal and navigate to the fsfe-website repository on your computer. Now type or copy/paste:
git config --add remote.upstream.fetch "+refs/pull/*/head:refs/remotes/upstream/pr/*"
The above command adds another reference your git asks for information from the upstream remote. It translates this location to a branch you can work with.
Afterwards, you can enter any existing pull request of this repository just like a branch. For example, Pull Request #42 can be checked out with:
git fetch upstream git checkout upstream/pr/42
Please note that you cannot make edits in the pull request this way, so a push is not possible. If you would like to work together as a team on a shared branch, there are other ways. Please ask the web@ mailing list for instructions.
In our XHTML files, you can set some invisible information which affects how fsfe.org and individual sub-sites appear for search engines and on social networks. It can also set some other parts of the website, e.g. for a link to the discussion/comments forum or the tags.
Meta elements provide useful metadata to a website. For fsfe.org, you can use the well-known description and keywords. Meta elements are places inside the <head> element. For example, this is how it looks like in index.en.xhtml:
<meta name="description" content="Non profit organisation working to create general understanding and support for software freedom. Includes news, events, and campaigns." /> <meta name="keywords" content="fsfe free software open source foss floss oss fsf government public sector gpl" />
You can check the source code of the built website in your browser, or paste the URL in opengraphcheck.com to verify that everything works.
When a link to a website on fsfe.org is shared on a social network or any other site supporting this feature, one can see a small preview image and text. For the text, the above "description" meta element is used, or alternatively the first paragraph if the former is not existent.
You can also configure the image. Per default, the FSFE logo is being used. But with adding the following element, you can change it. Please note that you should always use an absolute URL, and it should start with https://fsfe.org/ and not be an external URL. It should be located after </body>, but before the final closing </html> element. For example, on /order/order.en.xhtml it looks like the following:
<image url="https://fsfe.org/graphics/tshirt-promo-800px.jpg" />
Translators do a tremendous job to make fsfe.org accessible for as many people as possible. That is why we encourage them to claim credit for their work. Any translator can add the <translator> tag in their works. It has to be after the body element (so under </body>, but before the final closing </html> element. For example in /news/2019/news-20190124-01.nl.html, André did it like this in line 66:
The result is visible on the final website in the footer section, in this example here. If there are multiple translators, just separate them with the equivalent of "and" in your language, or just commas.
You can display the authors of a news items or articles on fsfe.org with the <author> tag. For example, this page lists multiple authors. Here is an excerpt of how this tag is used after the </body> and before </html>:
<author id="albers" /> <author> <name>Fernando Sanjurjo</name> </author>
If the person is a FSFE team member, one can use the ID of a person (usually the surname). This takes the full name of a person, the avatar and a link from the people.en.xml file. You can also set a name manually, e.g. if the person is external from the FSFE.
In the example, "albers" is Erik Albers from the FSFE, and Fernando Sanjuro is manually set.
If you would like to provide a link to a downloadable resource, e.g. downloading a white paper in PDF form, you can do this via the <download> tag. On this page, we offer a PDF download in this form:
<download type="pdf" content="https://fsfe.org/activities/policy/eu/20170105-horizon2020-position-paper.pdf" />
The value of type just sets the text of the link. "content" sets the actual link to the downloadable resource.
On fsfe.org, you can tag news and event items and other sites, although only news and events are currently completely searchable via tags. You can use it like the following, taken from this page:
<tags> <tag>front-page</tag> <tag content="Public Money Public Code">pmpc</tag> <tag content="Policy">policy</tag> <tag content="Public procurement">procurement</tag> <tag content="European Parliament">ep</tag> <tag content="Public Administration">publicadministration</tag> </tags>
Each tag is in a separate <tag>, and all tags altogether are capsuled within the <tags> tag.
The text after content=" of each tag is the visible text of this tag on the website, while the text between the > and < is the internally, unique tag. Please do not introduce new tags without checking back with the web team.
For news, newsletters, or podcasts you can link to a discussion topic on our Discourse instance. This way, interested minds can elaborate and exchange there. The link will be displayed below the article. An example is available in this news item.
In the XHTML file, please add after the closing </body> and before the closing </html>:
<discussion href="https://community.fsfe.org/t/test-news-item-for-testing-purposes/231" />
Regarding the procedure for that, we recommend following steps:
Create a topic in the reserved, hidden category FSFE News Preparation.
- Insert the news item's title, its teaser and a link to the full article (which you probably already know based on the release date).
If you saved the topic, click on the 3 dots below the newly created post. Then, click on the wrench symbol and on Change Ownership. Select the user FSFE as the new owner of the post.
If you published the news item, move the topic to the FSFE News category (or the respective one for the podcast) to enable normal users to see it. This can be done using the pen symbol next to the topic's title.
You have to be member of the Staff group to make these steps in Discourse. Ask its maintainers to give you access if necessary.
Licensing your source code
- When writing scripts on behalf of FSFE, please put them under AGPLv3+ (That is AGPL 3.0 with the addition "or any later version")
When introducing scripts from 3rd parties, please make sure they are under a Free Software License listed on http://www.gnu.org/licenses/license-list.html
- When you write scripts for FSFE (but are not employed by FSFE) we would prefer to have the script licensed under AGPLv3+, GPLv3+, LGPLv3+, Apache 2.0 or CC0, licensing the code under a Free Software License is mandatory for FSFE in order to deploy it.
Use custom licensed media
If you use images or other media which which has been licensed using a Creative Commons license or another license, you can make sure that the proper licensing information is displayed by adding these at the end of the document before </html>. Here are three examples:
<legal type="cc-license"> <license>https://creativecommons.org/licenses/by-sa/3.0/</license> <notice>This work is published under the Creative Commons BY-SA 3.0 Unported license by John Doe</notice> </legal>
<legal> <license>http://www.gnu.org/licenses/fdl-1.3.txt</license> <notice>This page is published under the GNU Free Documentation License 1.3 or later</notice> </legal>
<legal> <notice>This work is published under the CC-BY-SA 3.0 Unported license or the <a href="http://artlibre.org/">Licence Art Libre 1.3</a> at your option, etc.</notice> </legal>