Diff for "KnowHow/FSFELife/EditorialGuidelines"

Differences between revisions 3 and 4
Revision 3 as of 2017-08-20 15:53:26
Size: 9404
Editor: max.mehl
Comment:
Revision 4 as of 2017-08-21 08:55:50
Size: 9400
Editor: max.mehl
Comment: formatting
Deletions are marked like this. Additions are marked like this.
Line 12: Line 12:
 * 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 account and the necessary procedures can be found on [[https://wiki.fsfe.org/KnowHow/FSFELife/VolunteerAccountCreation|this dedicated wiki page]].
Line 13: Line 14:
 * 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 account 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]]
To have write access to the Git repository just write to [[mailto:system-hackers@lists.fsfe.org|system-hackers@lists.fsfe.org]]

Working with the website source

Getting access to the web pages

The source files for the web pages are stored on the fsfe-website Git repository, hosted on the FSFE's Git service. Other services are also available on the related Git instance.

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 account and the necessary procedures can be found on this dedicated wiki page.

To have write access to the Git repository just write to system-hackers@lists.fsfe.org

Checking out the Git fsfe-website repository

First of all, you should be familiar with our Git. You should already have an account on git.fsfe.org and feel secure with working in a Git repository. For this you can find help on TechDocs/Git and the specific guides First Steps and First Commit.

To download the fsfe-website repository which currently contains the source of fsfe.org, pfdreaders.org and drm.info, you have to clone the Git repository to your computer:

git clone git@git.fsfe.org:FSFE/fsfe-website.git

This command will create the directory fsfe-website in the current working directory of your command line terminal. If you want the local repository to be located somewhere else, create and/or change to another location on your computer.

Edit and push files to the website

Before any change you should update your local copy to fetch the latest changes:

git pull

Now you can make the changes on the files on your computer. To have an overview which files you have edited, you can show the files which differ between your local copy and the latest master:

git status

As soon as you are ready to upload your changes to the website, you have to add your changes to the index. Then you have to commit the files to have them tracked. As the last step, you have to push them to the server.

Let's say you have edited work.en.xhtml and /about/mission.en.xhtml and want to upload these changes to the website. Open a terminal at the root of the fsfe-website copy on your computer and execute carefully:

git status                                      # this will show you the changed files
git diff                                        # shows the differences between the original files and your changes
git add work.en.xhtml /about/mission.en.xhtml   # mark the files for commit
git status                                      # the two files are still visible but are now in the so-called "staging area"
git commit -m "write a short message here what you have changed"

Until here, all changes are still only on your local copy. To upload your modifications to the server, run:

git push

You should now be able to see your pushed commit in the repository's commit log

Coordination tools

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 corrent.

  • 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:

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 git@git.fsfe.org. Otherwise you will have to type in your Fellowhship 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 https://fsfe.org/, and the test branch, which is used to build https://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

Licensing

Licensing your source code

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 undere 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>

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