Diff for "KnowHow/FSFELife/EditorialGuidelines"

Differences between revisions 14 and 15
Revision 14 as of 2018-08-13 15:57:01
Size: 10243
Editor: alex.busch
Comment:
Revision 15 as of 2018-08-14 12:24:07
Size: 4303
Editor: alex.busch
Comment:
Deletions are marked like this. Additions are marked like this.
Line 7: Line 7:
= Creating a new slide to appear on the slider = = General information on working with the FSFE website source =
Line 9: Line 9:
1. First of all you will have to create/choose an image to be used as a background for the slide. You will find all the pictures used for slider here: `~FSFE/fsfe-website/graphics/`.
After image is ready it has to be also added there. Please consider using .jpg format to make it lightweight.
/!\ Please, read the information on [[TechDocs/Mainpage/Editing|TechDocs/Mainpage/Editing]], it is necessary for getting access to web pages and coordinating your work with others.
Line 12: Line 11:
(!)Note: if you would like your slide to contain text, it is best to create it as a separate item, which will make your slide adaptable to different screen resolutions. = Image Slider =
Line 14: Line 13:
2. current slides are to be found in `~FSFE/fsfe-website/tools/frontpage`, they are numbered according to the order they appear in: 10_xxxx.en.xml, here you can change the text and link for the slider, This page will help you modify or update the image slider on our [[https://fsfe/org|front page]].
From time to time it is necessary to update the content shown on slides or change the order of existing slides.
Line 16: Line 16:
3. To edit the font for the text, it's position on the page and other design related things, as well as adding a link to the related image, created in step 1, fsfe.less file has to be updated, located in == Creating a new slide to appear on the Home page ==

'''1.''' First of all you will have to create/choose an image to be used as a background for the slide.
You will find all the pictures currently used for slider here: `~FSFE/fsfe-website/graphics/`.
After background image `new_image.jpg` is ready it has to be added there also. Please consider using JPEG format to make images lightweight.<<BR>>

<<BR>>
(!) Note: if you would like your slide to contain text, it is best to add it as a separate item, which will allow the slide to be adaptable to different screen resolutions (mobile phones, tablets, etc.)<<BR>>
<<BR>>

'''2.''' Current slides are to be found in `~FSFE/fsfe-website/tools/frontpage`, they are numbered according to the order they appear in: `10_xxxx.en.xml`, `30_xxxx.en.xml`, etc.
By creating a new file like this, you can specify the text you want to appear on the slide and link it will lead to. Like this:
Line 19: Line 30:
fsfe-website/look/ <?xml version="1.0" encoding="UTF-8"?>
<campaigns>
    <campaign running="yes" id="newslide">
        <text>this is a new text</text>
        <link>/campaigns/newnew</link>
    </campaign>
</campaigns>
Line 22: Line 39:
4) After changing the fsfe.less modify fsfe.less, you need to compile your modifications into css, the process is described here: https://fsfe.org/contribute/web/css.en.html '''3.''' To edit the style of the text, it's position on the page, other design issues and to add a link to the image created in step 1, please update `fsfe.less` file, located in
Line 24: Line 41:
5) If you decide to help with designing something for the website it always best to check your modifications before creating a pull request in our main git repository, for this you will build the FSFE website locally, the process is described here: https://wiki.fsfe.org/TechDocs/Mainpage/BuildLocally
Please be aware that it might take a while to build FSFE website locally, but it will allow you to preview all the changes you make without waiting for the central build system.
 

= Working with the website source =

== Getting access to the web pages ==

The source files for the web pages are stored on the [[https://git.fsfe.org/fsfe/fsfe-website|fsfe-website Git repository]], hosted on the FSFE's Git service. Other services are also available on the related [[https://git.fsfe.org/|Git instance]].

To have access to these tools, just follow these instructions:

 * If you are a [[https://fsfe.org/fellowship|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 [[https://lists.fsfe.org/mailman/listinfo/web|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 [[https://wiki.fsfe.org/KnowHow/FSFELife/VolunteerAccountCreation|this dedicated wiki page]].

To have write access to the Git repository just write to [[mailto:system-hackers@lists.fsfe.org|system-hackers@lists.fsfe.org]]

== 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 [[/Teams/Web|Web Team]] and ask them to improve the Wiki page afterwards, so that others will not run into the same problem again.

== Enabling XML syntax check ==

In order to make sure that the XHTML and XML files you edit have a correct syntax and do not contain errors that may break the website, please install the pre-commit hooks we provide. This is a single command you have to execute from the root directory (i.e. first level) of the fsfe-website repository (or the fork you cloned):
`~FSFE/fsfe-website/fsfe-website/look/`. Here is the part of that documents, describing PMPC slide:
Line 50: Line 44:
ln -sr tools/githooks/* .git/hooks/         #boxpmpc {
            background: url('/graphics/pmpc_slider.jpg') left 33% no-repeat #666;
            background-size: cover;
            text-shadow: 0px 1px 8px rgb(0,0,0);

            .text, .text2 {
                .quote;
            }
            .text, .text2 {
                display: block;
                padding: 1.25em;
                min-width: 120px;
                font-size: 1.25em;
                hyphens: none;
                text-align: center;
            }
Line 53: Line 62:
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. '''4.''' After changing the `fsfe.less`, you need to compile your modifications into css, the whole process is described on this [[https://fsfe.org/contribute/web/css.en.html|page]] and won't take long.
Line 55: Line 64:
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.

= Coordination tools =

The work on the website pages is coordinated on the [[http://lists.fsfe.org/mailman/listinfo/web|Webmasters mailing list]].

In the fsfe-website repository's web interface you can find an issue tracker and the commit log.

The [[http://wiki.fsfe.org/Teams/Web|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 [[http://lists.fsfe.org/mailman/listinfo/web-cvs-notify|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 [[http://lists.fsfe.org/mailman/listinfo/web|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 [[http://lists.fsfe.org/mailman/listinfo/translators|Translators mailing list]] to ask for proofreading ([[https://fsfe.org/contribute/translators|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.


= Advanced information =

== Read-only access ==

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:
* First, you will have to install [[http://lesscss.org/|LESS]] if you haven't done so yet.
Line 93: Line 67:
git clone https://git.fsfe.org/FSFE/fsfe-website.git sudo apt-get install node-less

or

sudo apt-get install npm
sudo npm install -g less
Line 96: Line 75:
But if you want to edit the website source we encourage you to use the SSH clone link starting with {{{git@git.fsfe.org}}}. Otherwise you will have to type in your Fellowship account credentials every time you push a change. * After that just follow the instructions given in the [[https://fsfe.org/contribute/web/css.en.html|guide]].
Line 98: Line 77:
== The test branch == (!) Please, remember if you modify ''style.less'', you will need to compile all css.<<BR>>
<<BR>>
'''5.''' If you decide to help with designing something for the website it always best to check your modifications before publishing.<<BR>>

* ''The test branch''
Line 108: Line 91:
== Licensing == <<BR>>
* ''Building locally''
Line 110: Line 94:
=== Licensing your source code === You can build the fsfe.org website on your own computer to make previews of single pages possible offline and without having to wait for an online website build. The process of building the FSFE website locally is described here: [[https://wiki.fsfe.org/TechDocs/Mainpage/BuildLocally|/TechDocs/Mainpage/BuildLocally]]
Line 112: Line 96:
Whenever you introduce either server side program code (i.e. PHP, Perl) or JavaScript code to the website, please make sure you comply with our licensing policies. Specifically this means:


 * 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>
}}}
Please be aware that it might take a while to build FSFE website locally.

Attention this page is under construction!

General information on working with the FSFE website source

/!\ Please, read the information on TechDocs/Mainpage/Editing, it is necessary for getting access to web pages and coordinating your work with others.

Image Slider

This page will help you modify or update the image slider on our front page. From time to time it is necessary to update the content shown on slides or change the order of existing slides.

Creating a new slide to appear on the Home page

1. First of all you will have to create/choose an image to be used as a background for the slide. You will find all the pictures currently used for slider here: ~FSFE/fsfe-website/graphics/. After background image new_image.jpg is ready it has to be added there also. Please consider using JPEG format to make images lightweight.


(!) Note: if you would like your slide to contain text, it is best to add it as a separate item, which will allow the slide to be adaptable to different screen resolutions (mobile phones, tablets, etc.)

2. Current slides are to be found in ~FSFE/fsfe-website/tools/frontpage, they are numbered according to the order they appear in: 10_xxxx.en.xml, 30_xxxx.en.xml, etc. By creating a new file like this, you can specify the text you want to appear on the slide and link it will lead to. Like this:

<?xml version="1.0" encoding="UTF-8"?>
<campaigns>
    <campaign running="yes" id="newslide">
        <text>this is a new text</text>
        <link>/campaigns/newnew</link>
    </campaign>
</campaigns>

3. To edit the style of the text, it's position on the page, other design issues and to add a link to the image created in step 1, please update fsfe.less file, located in

~FSFE/fsfe-website/fsfe-website/look/. Here is the part of that documents, describing PMPC slide:

        #boxpmpc {
            background: url('/graphics/pmpc_slider.jpg')  left 33%  no-repeat #666;
            background-size: cover;
            text-shadow: 0px 1px 8px rgb(0,0,0);

            .text, .text2 {
                .quote;
            }
            .text, .text2 {
                display: block;
                padding: 1.25em;
                min-width: 120px;
                font-size: 1.25em;
                hyphens: none;
                text-align: center;
            }

4. After changing the fsfe.less, you need to compile your modifications into css, the whole process is described on this page and won't take long.

* First, you will have to install LESS if you haven't done so yet.

sudo apt-get install node-less

or

sudo apt-get install npm
sudo npm install -g less

* After that just follow the instructions given in the guide.

(!) Please, remember if you modify style.less, you will need to compile all css.

5. If you decide to help with designing something for the website it always best to check your modifications before publishing.

* 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


* Building locally

You can build the fsfe.org website on your own computer to make previews of single pages possible offline and without having to wait for an online website build. The process of building the FSFE website locally is described here: /TechDocs/Mainpage/BuildLocally

Please be aware that it might take a while to build FSFE website locally.

KnowHow/FSFELife/EditorialGuidelines (last edited 2018-09-10 08:52:38 by alex.busch)