From 0f30b5693442646bedf63b383ca6b0bd6db88ff6 Mon Sep 17 00:00:00 2001 From: Justin W. Flory (he/him) [Fedora Project] Date: Nov 03 2021 15:42:03 +0000 Subject: [PATCH 1/3] Temporarily relocate old documentation Signed-off-by: Justin W. Flory (he/him) [Fedora Project] --- diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 9eea7a5..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,177 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build - -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/FedoraWebsites.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/FedoraWebsites.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/FedoraWebsites" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/FedoraWebsites" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -latexpdfja: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index be44b45..0000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. Fedora Websites documentation master file, created by - sphinx-quickstart on Mon Feb 22 09:57:22 2016. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -=============== -Fedora Websites -=============== - -Contents: - -.. toctree:: - :maxdepth: 2 - - websites_release - -This page contains information about the Fedora Websites team. - -.. _websites-contact-info: - -Contact Information -=================== - -* IRC: ``#fedora-websites`` on irc.libera.chat -* Mailing List: `websites@lists.fedoraproject.org `_ -* Issue tracker: `Fedora Websites Trac Tickets `_ - -What does the Websites team do -============================== - -The Fedora Websites initiative aims to improve Fedora's image and to create the best possible interface for users and contributors on the Internet. The key goals of this effort include: - -* Consolidating all key Fedora websites onto one uniform scheme -* Maintaining content that doesn't fall under any particular sub-project -* Generally, making the sites as fun and exciting as the project they represent - -In order to better achieve these goals, as well as to benefit the community, the work of this project will involve third-party site maintainers where possible. The direct work of this project is limited to the formal `Get Fedora website `_. - -Work on specific sections of the sites will be coordinated by the appropriate projects. A great deal of coordination will be necessary with the `Fedora Infrastructure Team `_ , `Fedora Documentation Project `_ and the `Fedora Marketing Project `_. - -Joining the Websites team -========================= - -If you're interested in helping the Websites team, please refer to our `Join page `_. -Most discussions about websites happen in ``#fedora-websites``, so just pass by and say hello. - -Bugfixing -========= - -If you found a bug in the websites want to fix it by yourself, read the `instructions how to fix bugs on the Fedora websites `_. Otherwise please report them in the `Websites trac `_. - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/docs/source/websites_release.rst b/docs/source/websites_release.rst deleted file mode 100644 index a4b00f8..0000000 --- a/docs/source/websites_release.rst +++ /dev/null @@ -1,354 +0,0 @@ - -=================== -Webites Release SOP -=================== - -Preparing the website for a new release cycle -============================================= - -* Obsolete GPG key - - One month after a Fedora release the release number 'FXX-2' (i.e. 1 month - after F21 release, F19 will be EOL) will be EOL (End of Life). - At this point we should drop the GPG key from the list in ``verify/`` and move - the keys to the obsolete keys page in keys/obsolete.html. - -* Update GPG key - - After another couple of weeks and as the next release approaches, watch - the fedora-release package for a new key to be added. Use the update-gpg-keys - script in the fedora-web git repository to add it to ``static/``. Manually add it - to ``/keys`` and ``/verify`` in all websites where we use these keys: - - * arm.fpo - * getfedora.org - * labs.fpo - * spins.fpo - - -* Steps - - * Get a copy of the new key(s) from the fedora-release repo, you will - find FXX-primary and FXX-secondary keys. Save them in ``./tools`` to make the - update easier. - https://pagure.io/fedora-repos - - * Start by editing ``./tools/update-gpg-keys`` and adding the key-ids of - any obsolete keys to the obsolete_keys list. - - * Then run that script to add the new key(s) to the fedora.gpg block: - - :: - - fedora-web git:(master) cd tools/ - tools git:(master) ./update-gpg-keys RPM-GPG-KEY-fedora-23-primary - tools git:(master) ./update-gpg-keys RPM-GPG-KEY-fedora-23-secondary - - This will add the key(s) to the keyblock in ``static/fedora.gpg`` and - create a text file for the key in ``static/$KEYID.txt`` as well. Verify - that these files have been created properly and contain all the keys - that they should. - - * Handy checks: - - :: - - gpg static/fedora.gpg - - or - - gpg static/$KEYID.txt - - * Adding ``--with-fingerprint`` option will add the fingerprint to the - output - - The output of fedora.gpg should contain only the actual keys, not the - obsolete keys. - The single text files should contain the correct information for the - uploaded key. - - * Next, add new key(s) to the list in ``data/verify.html`` and move the new - key informations in the keys page in ``data/content/keys/index.html``. A - script to aid in generating the HTML code for new keys is in - ``./tools/make-gpg-key-html``. - It will print HTML to stdout for each RPM-GPG-KEY-* file given as - arguments. This is suitable for copy/paste (or directly importing if - your editor supports this). - Check the copied HTML code and select if the key info is for a primary - or secondary key (output says 'Primary or Secondary'). - - :: - - tools git:(master) ./make-gpg-key-html RPM-GPG-KEY-fedora-23-primary - - Build the website with ``make en test`` and carefully verify that the - data is correct. Please double check all keys in ``http://localhost:5000/en/keys`` - and ``http://localhost:5000/en/verify``. - - .. note:: - - NOTE: the tool will give you an outdated output, adapt it to the new - websites and bootstrap layout! - - -Update website for Alpha release -================================ - -* Create the fXX-alpha branch from master - - :: - - fedora-web git:(master) git push origin master:refs/heads/f23-alpha - - and checkout to the new branch: - - :: - - fedora-web git:(master) git checkout -t -b f23-alpha origin/f23-alpha - -* Update the global variables changing ``curr_state`` to Alpha for all architectures. - -* Add Alpha banner uploading it to ``static/images/banners/f23alpha.png`` - which should appear in every ``${PRODUCT}/download/index.html`` page. - Make sure the banner is shown in all sidebars, also in labs, spins, and arm.fp.o. - -* Check all Download links and paths in ``${PRODUCT}/prerelease/index.html`` - You can find all paths in bapp01 (sudo su - mirrormanager first) or - you can look at the downlaod page ``http://dl.fedoraproject.org/pub/alt/stage`` - -* Add CHECKSUM files to ``static/checksums`` and verify that the paths are - correct. The files should be in sundries01 and you can query them with: - - :: - - $ find /pub/fedora/linux/releases/test/23-Alpha/ -type f -name \ - *CHECKSUM* -exec cp '{}' . \; - - Remember to add the right checksums to the right websites (same path). - -* Add EC2 AMI IDs for Alpha. All IDs now are in the globalvar.py file. - We get all data from there, even the redirect path to trac the AMI IDs. - We now also have a script which is useful to get all the AMI IDs uploaded - with fedimg. Execute it to get the latest uploads, but don't run the script too - early, as new builds are added constantly. - - :: - - fedora-web git:(fXX-alpha) python ~/fedora-web/tools/get_ami.py - -* Add CHECKSUM files also to ``http://spins.fedoraproject.org`` in - ``static/checksums``. Verify the paths are correct in ``data/content/verify.html``. - (see point e) to query them on sundries01). Same for labs.fpo and arm.fpo. - -* Verify all paths and links on http://spins.fpo, labs.fpo and arm.fpo. - -* Update Alpha Image sizes and pre_cloud_composedate in ``./build.d/globalvar.py``. - Verify they are right in Cloud images and Docker image. - -* Update the new POT files and push them to translation repository every time - you change text strings. - -* Add this build to stg.fedoraproject.org (ansible syncStatic.sh.stg) to - test the pages online. - -* Release Date: - - * Merge the fXX-alpha branch to master and correct conflicts manually - * Remove the redirect of prerelease pages in ansible, edit: ``ansible/playbooks/include/proxies-redirects.yml``. Ask a sysadmin-main to run the playbook. - * When ready and about 90 minutes before Release Time, push to master - * Tag the commit as new release and push it too: - - :: - - $ git tag -a FXX-Alpha -m 'Releasing Fedora XX Alpha' - $ git push --tags - - * If needed follow `Fire in the Hole <#fire-in-the-hole>`_ - - -Update website for Beta release -================================ - -* Create the fXX-alpha branch from master - - :: - - fedora-web git:(master) git push origin master:refs/heads/f23-beta - - and checkout to the new branch: - - :: - - fedora-web git:(master) git checkout -t -b f23-beta origin/f23-beta - -* Update the global variables changing ``curr_state`` to Beta for all architectures. - -* Add Beta banner uploading it to ``static/images/banners/f23beta.png`` - which should appear in every ``${PRODUCT}/download/index.html`` page. - Make sure the banner is shown in all sidebars, also in labs, spins, and arm.fp.o. - -* Check all Download links and paths in ``${PRODUCT}/prerelease/index.html`` - You can find all paths in bapp01 (sudo su - mirrormanager first) or - you can look at the downlaod page ``http://dl.fedoraproject.org/pub/alt/stage`` - -* Add CHECKSUM files to ``static/checksums`` and verify that the paths are - correct. The files should be in sundries01 and you can query them with: - - :: - - $ find /pub/fedora/linux/releases/test/23-Beta/ -type f -name \ - *CHECKSUM* -exec cp '{}' . \; - - Remember to add the right checksums to the right websites (same path). - -* Add EC2 AMI IDs for Beta. All IDs now are in the globalvar.py file. - We get all data from there, even the redirect path to trac the AMI IDs. - We now also have a script which is useful to get all the AMI IDs uploaded - with fedimg. Execute it to get the latest uploads, but don't run the script too - early, as new builds are added constantly. - - :: - - fedora-web git:(fXX-beta) python ~/fedora-web/tools/get_ami.py - -* Add CHECKSUM files also to ``http://spins.fedoraproject.org`` in - ``static/checksums``. Verify the paths are correct in ``data/content/verify.html``. - (see point e) to query them on sundries01). Same for labs.fpo and arm.fpo. - -* Remove static/checksums/Fedora-XX-Alpha* in all websites. - -* Verify all paths and links on http://spins.fpo, labs.fpo and arm.fpo. - -* Update Beta Image sizes and pre_cloud_composedate in ``./build.d/globalvar.py``. - Verify they are right in Cloud images and Docker image. - -* Update the new POT files and push them to translation repository every time - you change text strings. - -* Add this build to stg.fedoraproject.org (ansible syncStatic.sh.stg) to - test the pages online. - -* Release Date: - - * Merge the fXX-beta branch to master and correct conflicts manually - * When ready and about 90 minutes before Release Time, push to master - * Tag the commit as new release and push it too: - - :: - - $ git tag -a FXX-Beta -m 'Releasing Fedora XX Beta' - $ git push --tags - - * If needed follow `Fire in the Hole <#fire-in-the-hole>`_ - - -Update website for GA -===================== - -* Create the fXX branch from master - - :: - - fedora-web git:(master) git push origin master:refs/heads/f23 - - and checkout to the new branch: - - :: - - fedora-web git:(master) git checkout -t -b f23 origin/f23 - -* Update the global variables changing ``curr_state`` to '' for all architectures. - -* Check all Download links and paths in ``${PRODUCT}/download/index.html`` - You can find all paths in bapp01 (sudo su - mirrormanager first) or - you can look at the downlaod page ``http://dl.fedoraproject.org/pub/alt/stage`` - -* Add CHECKSUM files to ``static/checksums`` and verify that the paths are - correct. The files should be in sundries01 and you can query them with: - - :: - - $ find /pub/fedora/linux/releases/23/ -type f -name \ - *CHECKSUM* -exec cp '{}' . \; - - Remember to add the right checksums to the right websites (same path). - -* At some point freeze translations. Add an empty PO_FREEZE file to every website's directory you want to freeze. - -* Add EC2 AMI IDs for GA. All IDs now are in the globalvar.py file. - We get all data from there, even the redirect path to trac the AMI IDs. - We now also have a script which is useful to get all the AMI IDs uploaded - with fedimg. Execute it to get the latest uploads, but don't run the script too - early, as new builds are added constantly. - - :: - - fedora-web git:(fXX) python ~/fedora-web/tools/get_ami.py - -* Add CHECKSUM files also to ``http://spins.fedoraproject.org`` in - ``static/checksums``. Verify the paths are correct in ``data/content/verify.html``. - (see point e) to query them on sundries01). Same for labs.fpo and arm.fpo. - -* Remove static/checksums/Fedora-XX-Beta* in all websites. - -* Verify all paths and links on http://spins.fpo, labs.fpo and arm.fpo. - -* Update GA Image sizes and pre_cloud_composedate in ``./build.d/globalvar.py``. - Verify they are right in Cloud images and Docker image. - -* Update static/js/checksum.js and check if the paths and checksum still match. - -* Update the new POT files and push them to translation repository every time - you change text strings. - -* Add this build to stg.fedoraproject.org (ansible syncStatic.sh.stg) to - test the pages online. - -* Release Date: - - * Merge the fXX branch to master and correct conflicts manually - * Add the redirect of prerelease pages in ansible, edit ``ansible/playbooks/include/proxies-redirects.yml``. - * Ask a sysadmin-main to run playbook - * Unfreeze translations by deleting the PO_FREEZE files - * When ready and about 90 minutes before Release Time, push to master - * Update the short links for the Cloud Images for 'Fedora XX', 'Fedora XX-1' and 'Latest' - * Tag the commit as new release and push it too: - - :: - - $ git tag -a FXX -m 'Releasing Fedora XX' - $ git push --tags - - * If needed follow `Fire in the Hole <#fire-in-the-hole>`_ - - -Fire in the hole -================ - -We now use ansible for everything, and normally use a regular build to make -the websites live. If something is not happening as expected, you should get in -contact with a sysadmin-main to run the ansible playbook again. - -All our puppet stuff, such as SyncStatic.sh and SyncTranslation.sh scripts are now -also in ansible! - -Staging server app02 and production server bapp01 do not exist anymore, now our staging -websites are on sundries01.stg and the production on sundries01. Change your scripts -accordingly and as sysadmin-web you should have access to those servers as before. - - -Tips -==== - -* Merging branches - - This can be useful if you're *sure* all new changes on devel branch should go into - the master branch. Conflicts will be solved directly accepting only the changes - in the devel branch. - If you're not 100% sure do a normal merge and fix conflicts manually! - - :: - - $ git merge f23-beta - $ git checkout --theirs f23-beta [list of conflicting po files] - $ git commit diff --git a/old_docs/Makefile b/old_docs/Makefile new file mode 100644 index 0000000..9eea7a5 --- /dev/null +++ b/old_docs/Makefile @@ -0,0 +1,177 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# User-friendly check for sphinx-build +ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) +$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) +endif + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/FedoraWebsites.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/FedoraWebsites.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/FedoraWebsites" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/FedoraWebsites" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/old_docs/source/index.rst b/old_docs/source/index.rst new file mode 100644 index 0000000..be44b45 --- /dev/null +++ b/old_docs/source/index.rst @@ -0,0 +1,59 @@ +.. Fedora Websites documentation master file, created by + sphinx-quickstart on Mon Feb 22 09:57:22 2016. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +=============== +Fedora Websites +=============== + +Contents: + +.. toctree:: + :maxdepth: 2 + + websites_release + +This page contains information about the Fedora Websites team. + +.. _websites-contact-info: + +Contact Information +=================== + +* IRC: ``#fedora-websites`` on irc.libera.chat +* Mailing List: `websites@lists.fedoraproject.org `_ +* Issue tracker: `Fedora Websites Trac Tickets `_ + +What does the Websites team do +============================== + +The Fedora Websites initiative aims to improve Fedora's image and to create the best possible interface for users and contributors on the Internet. The key goals of this effort include: + +* Consolidating all key Fedora websites onto one uniform scheme +* Maintaining content that doesn't fall under any particular sub-project +* Generally, making the sites as fun and exciting as the project they represent + +In order to better achieve these goals, as well as to benefit the community, the work of this project will involve third-party site maintainers where possible. The direct work of this project is limited to the formal `Get Fedora website `_. + +Work on specific sections of the sites will be coordinated by the appropriate projects. A great deal of coordination will be necessary with the `Fedora Infrastructure Team `_ , `Fedora Documentation Project `_ and the `Fedora Marketing Project `_. + +Joining the Websites team +========================= + +If you're interested in helping the Websites team, please refer to our `Join page `_. +Most discussions about websites happen in ``#fedora-websites``, so just pass by and say hello. + +Bugfixing +========= + +If you found a bug in the websites want to fix it by yourself, read the `instructions how to fix bugs on the Fedora websites `_. Otherwise please report them in the `Websites trac `_. + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/old_docs/source/websites_release.rst b/old_docs/source/websites_release.rst new file mode 100644 index 0000000..a4b00f8 --- /dev/null +++ b/old_docs/source/websites_release.rst @@ -0,0 +1,354 @@ + +=================== +Webites Release SOP +=================== + +Preparing the website for a new release cycle +============================================= + +* Obsolete GPG key + + One month after a Fedora release the release number 'FXX-2' (i.e. 1 month + after F21 release, F19 will be EOL) will be EOL (End of Life). + At this point we should drop the GPG key from the list in ``verify/`` and move + the keys to the obsolete keys page in keys/obsolete.html. + +* Update GPG key + + After another couple of weeks and as the next release approaches, watch + the fedora-release package for a new key to be added. Use the update-gpg-keys + script in the fedora-web git repository to add it to ``static/``. Manually add it + to ``/keys`` and ``/verify`` in all websites where we use these keys: + + * arm.fpo + * getfedora.org + * labs.fpo + * spins.fpo + + +* Steps + + * Get a copy of the new key(s) from the fedora-release repo, you will + find FXX-primary and FXX-secondary keys. Save them in ``./tools`` to make the + update easier. + https://pagure.io/fedora-repos + + * Start by editing ``./tools/update-gpg-keys`` and adding the key-ids of + any obsolete keys to the obsolete_keys list. + + * Then run that script to add the new key(s) to the fedora.gpg block: + + :: + + fedora-web git:(master) cd tools/ + tools git:(master) ./update-gpg-keys RPM-GPG-KEY-fedora-23-primary + tools git:(master) ./update-gpg-keys RPM-GPG-KEY-fedora-23-secondary + + This will add the key(s) to the keyblock in ``static/fedora.gpg`` and + create a text file for the key in ``static/$KEYID.txt`` as well. Verify + that these files have been created properly and contain all the keys + that they should. + + * Handy checks: + + :: + + gpg static/fedora.gpg + + or + + gpg static/$KEYID.txt + + * Adding ``--with-fingerprint`` option will add the fingerprint to the + output + + The output of fedora.gpg should contain only the actual keys, not the + obsolete keys. + The single text files should contain the correct information for the + uploaded key. + + * Next, add new key(s) to the list in ``data/verify.html`` and move the new + key informations in the keys page in ``data/content/keys/index.html``. A + script to aid in generating the HTML code for new keys is in + ``./tools/make-gpg-key-html``. + It will print HTML to stdout for each RPM-GPG-KEY-* file given as + arguments. This is suitable for copy/paste (or directly importing if + your editor supports this). + Check the copied HTML code and select if the key info is for a primary + or secondary key (output says 'Primary or Secondary'). + + :: + + tools git:(master) ./make-gpg-key-html RPM-GPG-KEY-fedora-23-primary + + Build the website with ``make en test`` and carefully verify that the + data is correct. Please double check all keys in ``http://localhost:5000/en/keys`` + and ``http://localhost:5000/en/verify``. + + .. note:: + + NOTE: the tool will give you an outdated output, adapt it to the new + websites and bootstrap layout! + + +Update website for Alpha release +================================ + +* Create the fXX-alpha branch from master + + :: + + fedora-web git:(master) git push origin master:refs/heads/f23-alpha + + and checkout to the new branch: + + :: + + fedora-web git:(master) git checkout -t -b f23-alpha origin/f23-alpha + +* Update the global variables changing ``curr_state`` to Alpha for all architectures. + +* Add Alpha banner uploading it to ``static/images/banners/f23alpha.png`` + which should appear in every ``${PRODUCT}/download/index.html`` page. + Make sure the banner is shown in all sidebars, also in labs, spins, and arm.fp.o. + +* Check all Download links and paths in ``${PRODUCT}/prerelease/index.html`` + You can find all paths in bapp01 (sudo su - mirrormanager first) or + you can look at the downlaod page ``http://dl.fedoraproject.org/pub/alt/stage`` + +* Add CHECKSUM files to ``static/checksums`` and verify that the paths are + correct. The files should be in sundries01 and you can query them with: + + :: + + $ find /pub/fedora/linux/releases/test/23-Alpha/ -type f -name \ + *CHECKSUM* -exec cp '{}' . \; + + Remember to add the right checksums to the right websites (same path). + +* Add EC2 AMI IDs for Alpha. All IDs now are in the globalvar.py file. + We get all data from there, even the redirect path to trac the AMI IDs. + We now also have a script which is useful to get all the AMI IDs uploaded + with fedimg. Execute it to get the latest uploads, but don't run the script too + early, as new builds are added constantly. + + :: + + fedora-web git:(fXX-alpha) python ~/fedora-web/tools/get_ami.py + +* Add CHECKSUM files also to ``http://spins.fedoraproject.org`` in + ``static/checksums``. Verify the paths are correct in ``data/content/verify.html``. + (see point e) to query them on sundries01). Same for labs.fpo and arm.fpo. + +* Verify all paths and links on http://spins.fpo, labs.fpo and arm.fpo. + +* Update Alpha Image sizes and pre_cloud_composedate in ``./build.d/globalvar.py``. + Verify they are right in Cloud images and Docker image. + +* Update the new POT files and push them to translation repository every time + you change text strings. + +* Add this build to stg.fedoraproject.org (ansible syncStatic.sh.stg) to + test the pages online. + +* Release Date: + + * Merge the fXX-alpha branch to master and correct conflicts manually + * Remove the redirect of prerelease pages in ansible, edit: ``ansible/playbooks/include/proxies-redirects.yml``. Ask a sysadmin-main to run the playbook. + * When ready and about 90 minutes before Release Time, push to master + * Tag the commit as new release and push it too: + + :: + + $ git tag -a FXX-Alpha -m 'Releasing Fedora XX Alpha' + $ git push --tags + + * If needed follow `Fire in the Hole <#fire-in-the-hole>`_ + + +Update website for Beta release +================================ + +* Create the fXX-alpha branch from master + + :: + + fedora-web git:(master) git push origin master:refs/heads/f23-beta + + and checkout to the new branch: + + :: + + fedora-web git:(master) git checkout -t -b f23-beta origin/f23-beta + +* Update the global variables changing ``curr_state`` to Beta for all architectures. + +* Add Beta banner uploading it to ``static/images/banners/f23beta.png`` + which should appear in every ``${PRODUCT}/download/index.html`` page. + Make sure the banner is shown in all sidebars, also in labs, spins, and arm.fp.o. + +* Check all Download links and paths in ``${PRODUCT}/prerelease/index.html`` + You can find all paths in bapp01 (sudo su - mirrormanager first) or + you can look at the downlaod page ``http://dl.fedoraproject.org/pub/alt/stage`` + +* Add CHECKSUM files to ``static/checksums`` and verify that the paths are + correct. The files should be in sundries01 and you can query them with: + + :: + + $ find /pub/fedora/linux/releases/test/23-Beta/ -type f -name \ + *CHECKSUM* -exec cp '{}' . \; + + Remember to add the right checksums to the right websites (same path). + +* Add EC2 AMI IDs for Beta. All IDs now are in the globalvar.py file. + We get all data from there, even the redirect path to trac the AMI IDs. + We now also have a script which is useful to get all the AMI IDs uploaded + with fedimg. Execute it to get the latest uploads, but don't run the script too + early, as new builds are added constantly. + + :: + + fedora-web git:(fXX-beta) python ~/fedora-web/tools/get_ami.py + +* Add CHECKSUM files also to ``http://spins.fedoraproject.org`` in + ``static/checksums``. Verify the paths are correct in ``data/content/verify.html``. + (see point e) to query them on sundries01). Same for labs.fpo and arm.fpo. + +* Remove static/checksums/Fedora-XX-Alpha* in all websites. + +* Verify all paths and links on http://spins.fpo, labs.fpo and arm.fpo. + +* Update Beta Image sizes and pre_cloud_composedate in ``./build.d/globalvar.py``. + Verify they are right in Cloud images and Docker image. + +* Update the new POT files and push them to translation repository every time + you change text strings. + +* Add this build to stg.fedoraproject.org (ansible syncStatic.sh.stg) to + test the pages online. + +* Release Date: + + * Merge the fXX-beta branch to master and correct conflicts manually + * When ready and about 90 minutes before Release Time, push to master + * Tag the commit as new release and push it too: + + :: + + $ git tag -a FXX-Beta -m 'Releasing Fedora XX Beta' + $ git push --tags + + * If needed follow `Fire in the Hole <#fire-in-the-hole>`_ + + +Update website for GA +===================== + +* Create the fXX branch from master + + :: + + fedora-web git:(master) git push origin master:refs/heads/f23 + + and checkout to the new branch: + + :: + + fedora-web git:(master) git checkout -t -b f23 origin/f23 + +* Update the global variables changing ``curr_state`` to '' for all architectures. + +* Check all Download links and paths in ``${PRODUCT}/download/index.html`` + You can find all paths in bapp01 (sudo su - mirrormanager first) or + you can look at the downlaod page ``http://dl.fedoraproject.org/pub/alt/stage`` + +* Add CHECKSUM files to ``static/checksums`` and verify that the paths are + correct. The files should be in sundries01 and you can query them with: + + :: + + $ find /pub/fedora/linux/releases/23/ -type f -name \ + *CHECKSUM* -exec cp '{}' . \; + + Remember to add the right checksums to the right websites (same path). + +* At some point freeze translations. Add an empty PO_FREEZE file to every website's directory you want to freeze. + +* Add EC2 AMI IDs for GA. All IDs now are in the globalvar.py file. + We get all data from there, even the redirect path to trac the AMI IDs. + We now also have a script which is useful to get all the AMI IDs uploaded + with fedimg. Execute it to get the latest uploads, but don't run the script too + early, as new builds are added constantly. + + :: + + fedora-web git:(fXX) python ~/fedora-web/tools/get_ami.py + +* Add CHECKSUM files also to ``http://spins.fedoraproject.org`` in + ``static/checksums``. Verify the paths are correct in ``data/content/verify.html``. + (see point e) to query them on sundries01). Same for labs.fpo and arm.fpo. + +* Remove static/checksums/Fedora-XX-Beta* in all websites. + +* Verify all paths and links on http://spins.fpo, labs.fpo and arm.fpo. + +* Update GA Image sizes and pre_cloud_composedate in ``./build.d/globalvar.py``. + Verify they are right in Cloud images and Docker image. + +* Update static/js/checksum.js and check if the paths and checksum still match. + +* Update the new POT files and push them to translation repository every time + you change text strings. + +* Add this build to stg.fedoraproject.org (ansible syncStatic.sh.stg) to + test the pages online. + +* Release Date: + + * Merge the fXX branch to master and correct conflicts manually + * Add the redirect of prerelease pages in ansible, edit ``ansible/playbooks/include/proxies-redirects.yml``. + * Ask a sysadmin-main to run playbook + * Unfreeze translations by deleting the PO_FREEZE files + * When ready and about 90 minutes before Release Time, push to master + * Update the short links for the Cloud Images for 'Fedora XX', 'Fedora XX-1' and 'Latest' + * Tag the commit as new release and push it too: + + :: + + $ git tag -a FXX -m 'Releasing Fedora XX' + $ git push --tags + + * If needed follow `Fire in the Hole <#fire-in-the-hole>`_ + + +Fire in the hole +================ + +We now use ansible for everything, and normally use a regular build to make +the websites live. If something is not happening as expected, you should get in +contact with a sysadmin-main to run the ansible playbook again. + +All our puppet stuff, such as SyncStatic.sh and SyncTranslation.sh scripts are now +also in ansible! + +Staging server app02 and production server bapp01 do not exist anymore, now our staging +websites are on sundries01.stg and the production on sundries01. Change your scripts +accordingly and as sysadmin-web you should have access to those servers as before. + + +Tips +==== + +* Merging branches + + This can be useful if you're *sure* all new changes on devel branch should go into + the master branch. Conflicts will be solved directly accepting only the changes + in the devel branch. + If you're not 100% sure do a normal merge and fix conflicts manually! + + :: + + $ git merge f23-beta + $ git checkout --theirs f23-beta [list of conflicting po files] + $ git commit From 4cee3d251ec7c9eda262a8a303ca43c6cd11e42d Mon Sep 17 00:00:00 2001 From: Justin W. Flory (he/him) [Fedora Project] Date: Nov 03 2021 15:42:16 +0000 Subject: [PATCH 2/3] Initial import of docs repo at https://pagure.io/fedora-docs/websites A new baseline of the initial docs website without any changes. Signed-off-by: Justin W. Flory (he/him) [Fedora Project] --- diff --git a/docs/LICENSE b/docs/LICENSE new file mode 100644 index 0000000..1495fc1 --- /dev/null +++ b/docs/LICENSE @@ -0,0 +1,360 @@ +Creative Commons Legal Code + +Attribution-ShareAlike 3.0 Unported + + CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE + LEGAL SERVICES. DISTRIBUTION OF THIS LICENSE DOES NOT CREATE AN + ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS + INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES + REGARDING THE INFORMATION PROVIDED, AND DISCLAIMS LIABILITY FOR + DAMAGES RESULTING FROM ITS USE. + +License + +THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE +COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY +COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS +AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED. + +BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE +TO BE BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS LICENSE MAY +BE CONSIDERED TO BE A CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS +CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND +CONDITIONS. + +1. Definitions + + a. "Adaptation" means a work based upon the Work, or upon the Work and + other pre-existing works, such as a translation, adaptation, + derivative work, arrangement of music or other alterations of a + literary or artistic work, or phonogram or performance and includes + cinematographic adaptations or any other form in which the Work may be + recast, transformed, or adapted including in any form recognizably + derived from the original, except that a work that constitutes a + Collection will not be considered an Adaptation for the purpose of + this License. For the avoidance of doubt, where the Work is a musical + work, performance or phonogram, the synchronization of the Work in + timed-relation with a moving image ("synching") will be considered an + Adaptation for the purpose of this License. + b. "Collection" means a collection of literary or artistic works, such as + encyclopedias and anthologies, or performances, phonograms or + broadcasts, or other works or subject matter other than works listed + in Section 1(f) below, which, by reason of the selection and + arrangement of their contents, constitute intellectual creations, in + which the Work is included in its entirety in unmodified form along + with one or more other contributions, each constituting separate and + independent works in themselves, which together are assembled into a + collective whole. A work that constitutes a Collection will not be + considered an Adaptation (as defined below) for the purposes of this + License. + c. "Creative Commons Compatible License" means a license that is listed + at https://creativecommons.org/compatiblelicenses that has been + approved by Creative Commons as being essentially equivalent to this + License, including, at a minimum, because that license: (i) contains + terms that have the same purpose, meaning and effect as the License + Elements of this License; and, (ii) explicitly permits the relicensing + of adaptations of works made available under that license under this + License or a Creative Commons jurisdiction license with the same + License Elements as this License. + d. "Distribute" means to make available to the public the original and + copies of the Work or Adaptation, as appropriate, through sale or + other transfer of ownership. + e. "License Elements" means the following high-level license attributes + as selected by Licensor and indicated in the title of this License: + Attribution, ShareAlike. + f. "Licensor" means the individual, individuals, entity or entities that + offer(s) the Work under the terms of this License. + g. "Original Author" means, in the case of a literary or artistic work, + the individual, individuals, entity or entities who created the Work + or if no individual or entity can be identified, the publisher; and in + addition (i) in the case of a performance the actors, singers, + musicians, dancers, and other persons who act, sing, deliver, declaim, + play in, interpret or otherwise perform literary or artistic works or + expressions of folklore; (ii) in the case of a phonogram the producer + being the person or legal entity who first fixes the sounds of a + performance or other sounds; and, (iii) in the case of broadcasts, the + organization that transmits the broadcast. + h. "Work" means the literary and/or artistic work offered under the terms + of this License including without limitation any production in the + literary, scientific and artistic domain, whatever may be the mode or + form of its expression including digital form, such as a book, + pamphlet and other writing; a lecture, address, sermon or other work + of the same nature; a dramatic or dramatico-musical work; a + choreographic work or entertainment in dumb show; a musical + composition with or without words; a cinematographic work to which are + assimilated works expressed by a process analogous to cinematography; + a work of drawing, painting, architecture, sculpture, engraving or + lithography; a photographic work to which are assimilated works + expressed by a process analogous to photography; a work of applied + art; an illustration, map, plan, sketch or three-dimensional work + relative to geography, topography, architecture or science; a + performance; a broadcast; a phonogram; a compilation of data to the + extent it is protected as a copyrightable work; or a work performed by + a variety or circus performer to the extent it is not otherwise + considered a literary or artistic work. + i. "You" means an individual or entity exercising rights under this + License who has not previously violated the terms of this License with + respect to the Work, or who has received express permission from the + Licensor to exercise rights under this License despite a previous + violation. + j. "Publicly Perform" means to perform public recitations of the Work and + to communicate to the public those public recitations, by any means or + process, including by wire or wireless means or public digital + performances; to make available to the public Works in such a way that + members of the public may access these Works from a place and at a + place individually chosen by them; to perform the Work to the public + by any means or process and the communication to the public of the + performances of the Work, including by public digital performance; to + broadcast and rebroadcast the Work by any means including signs, + sounds or images. + k. "Reproduce" means to make copies of the Work by any means including + without limitation by sound or visual recordings and the right of + fixation and reproducing fixations of the Work, including storage of a + protected performance or phonogram in digital form or other electronic + medium. + +2. Fair Dealing Rights. Nothing in this License is intended to reduce, +limit, or restrict any uses free from copyright or rights arising from +limitations or exceptions that are provided for in connection with the +copyright protection under copyright law or other applicable laws. + +3. License Grant. Subject to the terms and conditions of this License, +Licensor hereby grants You a worldwide, royalty-free, non-exclusive, +perpetual (for the duration of the applicable copyright) license to +exercise the rights in the Work as stated below: + + a. to Reproduce the Work, to incorporate the Work into one or more + Collections, and to Reproduce the Work as incorporated in the + Collections; + b. to create and Reproduce Adaptations provided that any such Adaptation, + including any translation in any medium, takes reasonable steps to + clearly label, demarcate or otherwise identify that changes were made + to the original Work. For example, a translation could be marked "The + original work was translated from English to Spanish," or a + modification could indicate "The original work has been modified."; + c. to Distribute and Publicly Perform the Work including as incorporated + in Collections; and, + d. to Distribute and Publicly Perform Adaptations. + e. For the avoidance of doubt: + + i. Non-waivable Compulsory License Schemes. In those jurisdictions in + which the right to collect royalties through any statutory or + compulsory licensing scheme cannot be waived, the Licensor + reserves the exclusive right to collect such royalties for any + exercise by You of the rights granted under this License; + ii. Waivable Compulsory License Schemes. In those jurisdictions in + which the right to collect royalties through any statutory or + compulsory licensing scheme can be waived, the Licensor waives the + exclusive right to collect such royalties for any exercise by You + of the rights granted under this License; and, + iii. Voluntary License Schemes. The Licensor waives the right to + collect royalties, whether individually or, in the event that the + Licensor is a member of a collecting society that administers + voluntary licensing schemes, via that society, from any exercise + by You of the rights granted under this License. + +The above rights may be exercised in all media and formats whether now +known or hereafter devised. The above rights include the right to make +such modifications as are technically necessary to exercise the rights in +other media and formats. Subject to Section 8(f), all rights not expressly +granted by Licensor are hereby reserved. + +4. Restrictions. The license granted in Section 3 above is expressly made +subject to and limited by the following restrictions: + + a. You may Distribute or Publicly Perform the Work only under the terms + of this License. You must include a copy of, or the Uniform Resource + Identifier (URI) for, this License with every copy of the Work You + Distribute or Publicly Perform. You may not offer or impose any terms + on the Work that restrict the terms of this License or the ability of + the recipient of the Work to exercise the rights granted to that + recipient under the terms of the License. You may not sublicense the + Work. You must keep intact all notices that refer to this License and + to the disclaimer of warranties with every copy of the Work You + Distribute or Publicly Perform. When You Distribute or Publicly + Perform the Work, You may not impose any effective technological + measures on the Work that restrict the ability of a recipient of the + Work from You to exercise the rights granted to that recipient under + the terms of the License. This Section 4(a) applies to the Work as + incorporated in a Collection, but this does not require the Collection + apart from the Work itself to be made subject to the terms of this + License. If You create a Collection, upon notice from any Licensor You + must, to the extent practicable, remove from the Collection any credit + as required by Section 4(c), as requested. If You create an + Adaptation, upon notice from any Licensor You must, to the extent + practicable, remove from the Adaptation any credit as required by + Section 4(c), as requested. + b. You may Distribute or Publicly Perform an Adaptation only under the + terms of: (i) this License; (ii) a later version of this License with + the same License Elements as this License; (iii) a Creative Commons + jurisdiction license (either this or a later license version) that + contains the same License Elements as this License (e.g., + Attribution-ShareAlike 3.0 US)); (iv) a Creative Commons Compatible + License. If you license the Adaptation under one of the licenses + mentioned in (iv), you must comply with the terms of that license. If + you license the Adaptation under the terms of any of the licenses + mentioned in (i), (ii) or (iii) (the "Applicable License"), you must + comply with the terms of the Applicable License generally and the + following provisions: (I) You must include a copy of, or the URI for, + the Applicable License with every copy of each Adaptation You + Distribute or Publicly Perform; (II) You may not offer or impose any + terms on the Adaptation that restrict the terms of the Applicable + License or the ability of the recipient of the Adaptation to exercise + the rights granted to that recipient under the terms of the Applicable + License; (III) You must keep intact all notices that refer to the + Applicable License and to the disclaimer of warranties with every copy + of the Work as included in the Adaptation You Distribute or Publicly + Perform; (IV) when You Distribute or Publicly Perform the Adaptation, + You may not impose any effective technological measures on the + Adaptation that restrict the ability of a recipient of the Adaptation + from You to exercise the rights granted to that recipient under the + terms of the Applicable License. This Section 4(b) applies to the + Adaptation as incorporated in a Collection, but this does not require + the Collection apart from the Adaptation itself to be made subject to + the terms of the Applicable License. + c. If You Distribute, or Publicly Perform the Work or any Adaptations or + Collections, You must, unless a request has been made pursuant to + Section 4(a), keep intact all copyright notices for the Work and + provide, reasonable to the medium or means You are utilizing: (i) the + name of the Original Author (or pseudonym, if applicable) if supplied, + and/or if the Original Author and/or Licensor designate another party + or parties (e.g., a sponsor institute, publishing entity, journal) for + attribution ("Attribution Parties") in Licensor's copyright notice, + terms of service or by other reasonable means, the name of such party + or parties; (ii) the title of the Work if supplied; (iii) to the + extent reasonably practicable, the URI, if any, that Licensor + specifies to be associated with the Work, unless such URI does not + refer to the copyright notice or licensing information for the Work; + and (iv) , consistent with Ssection 3(b), in the case of an + Adaptation, a credit identifying the use of the Work in the Adaptation + (e.g., "French translation of the Work by Original Author," or + "Screenplay based on original Work by Original Author"). The credit + required by this Section 4(c) may be implemented in any reasonable + manner; provided, however, that in the case of a Adaptation or + Collection, at a minimum such credit will appear, if a credit for all + contributing authors of the Adaptation or Collection appears, then as + part of these credits and in a manner at least as prominent as the + credits for the other contributing authors. For the avoidance of + doubt, You may only use the credit required by this Section for the + purpose of attribution in the manner set out above and, by exercising + Your rights under this License, You may not implicitly or explicitly + assert or imply any connection with, sponsorship or endorsement by the + Original Author, Licensor and/or Attribution Parties, as appropriate, + of You or Your use of the Work, without the separate, express prior + written permission of the Original Author, Licensor and/or Attribution + Parties. + d. Except as otherwise agreed in writing by the Licensor or as may be + otherwise permitted by applicable law, if You Reproduce, Distribute or + Publicly Perform the Work either by itself or as part of any + Adaptations or Collections, You must not distort, mutilate, modify or + take other derogatory action in relation to the Work which would be + prejudicial to the Original Author's honor or reputation. Licensor + agrees that in those jurisdictions (e.g. Japan), in which any exercise + of the right granted in Section 3(b) of this License (the right to + make Adaptations) would be deemed to be a distortion, mutilation, + modification or other derogatory action prejudicial to the Original + Author's honor and reputation, the Licensor will waive or not assert, + as appropriate, this Section, to the fullest extent permitted by the + applicable national law, to enable You to reasonably exercise Your + right under Section 3(b) of this License (right to make Adaptations) + but not otherwise. + +5. Representations, Warranties and Disclaimer + +UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING, LICENSOR +OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY +KIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, +INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY, +FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF +LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, +WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION +OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU. + +6. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE +LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR +ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES +ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS +BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + +7. Termination + + a. This License and the rights granted hereunder will terminate + automatically upon any breach by You of the terms of this License. + Individuals or entities who have received Adaptations or Collections + from You under this License, however, will not have their licenses + terminated provided such individuals or entities remain in full + compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will + survive any termination of this License. + b. Subject to the above terms and conditions, the license granted here is + perpetual (for the duration of the applicable copyright in the Work). + Notwithstanding the above, Licensor reserves the right to release the + Work under different license terms or to stop distributing the Work at + any time; provided, however that any such election will not serve to + withdraw this License (or any other license that has been, or is + required to be, granted under the terms of this License), and this + License will continue in full force and effect unless terminated as + stated above. + +8. Miscellaneous + + a. Each time You Distribute or Publicly Perform the Work or a Collection, + the Licensor offers to the recipient a license to the Work on the same + terms and conditions as the license granted to You under this License. + b. Each time You Distribute or Publicly Perform an Adaptation, Licensor + offers to the recipient a license to the original Work on the same + terms and conditions as the license granted to You under this License. + c. If any provision of this License is invalid or unenforceable under + applicable law, it shall not affect the validity or enforceability of + the remainder of the terms of this License, and without further action + by the parties to this agreement, such provision shall be reformed to + the minimum extent necessary to make such provision valid and + enforceable. + d. No term or provision of this License shall be deemed waived and no + breach consented to unless such waiver or consent shall be in writing + and signed by the party to be charged with such waiver or consent. + e. This License constitutes the entire agreement between the parties with + respect to the Work licensed here. There are no understandings, + agreements or representations with respect to the Work not specified + here. Licensor shall not be bound by any additional provisions that + may appear in any communication from You. This License may not be + modified without the mutual written agreement of the Licensor and You. + f. The rights granted under, and the subject matter referenced, in this + License were drafted utilizing the terminology of the Berne Convention + for the Protection of Literary and Artistic Works (as amended on + September 28, 1979), the Rome Convention of 1961, the WIPO Copyright + Treaty of 1996, the WIPO Performances and Phonograms Treaty of 1996 + and the Universal Copyright Convention (as revised on July 24, 1971). + These rights and subject matter take effect in the relevant + jurisdiction in which the License terms are sought to be enforced + according to the corresponding provisions of the implementation of + those treaty provisions in the applicable national law. If the + standard suite of rights granted under applicable copyright law + includes additional rights not granted under this License, such + additional rights are deemed to be included in the License; this + License is not intended to restrict the license of any rights under + applicable law. + + +Creative Commons Notice + + Creative Commons is not a party to this License, and makes no warranty + whatsoever in connection with the Work. Creative Commons will not be + liable to You or any party on any legal theory for any damages + whatsoever, including without limitation any general, special, + incidental or consequential damages arising in connection to this + license. Notwithstanding the foregoing two (2) sentences, if Creative + Commons has expressly identified itself as the Licensor hereunder, it + shall have all rights and obligations of Licensor. + + Except for the limited purpose of indicating to the public that the + Work is licensed under the CCPL, Creative Commons does not authorize + the use by either party of the trademark "Creative Commons" or any + related trademark or logo of Creative Commons without the prior + written consent of Creative Commons. Any permitted use will be in + compliance with Creative Commons' then-current trademark usage + guidelines, as may be published on its website or otherwise made + available upon request from time to time. For the avoidance of doubt, + this trademark restriction does not form part of the License. + + Creative Commons may be contacted at https://creativecommons.org/. + diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..49fb545 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,120 @@ +# Fedora Websites docs + +This repository documentation for maintaining and adding new Fedora websites. + +## Structure + +``` +|-- README.md +|-- antora.yml ....................... 1. +|-- build.sh ......................... 2. +|-- preview.sh ....................... 3. +|-- site.yml ......................... 4. +`-- modules + `-- ROOT ......................... 5. + |-- assets + | `-- images ............... 6. + | `-- pizza.png + |-- nav.adoc ................. 7. + `-- pages .................... 8. + |-- architecture.adoc + |-- community.adoc + |-- faq.adoc + |-- index.adoc + |-- pizza-dough.adoc + `-- pizza-owen.adoc +``` + +1. Metadata definition. +2. A script that does a local build. Uses docker. +3. A script that shows a preview of the site in a web browser by running a local web server. Uses docker. +4. A definition file for the build script. +5. A "root module of this documentation component". Please read below for an explanation. +6. **Images** to be used on any page. +7. **Menu definition.** Also defines the hierarchy of all the pages. +8. **Pages with the actual content.** They can be also organised into subdirectories if desired. + +## Components and Modules + +Antora introduces two new terms: + +* **Component** — Simply put, a component is a part of the documentation website with its own menu. Components can also be versioned. In the Fedora Docs, we use separate components for user documentation, the Fedora Poject, Fedora council, Mindshare, FESCO, but also subprojects such as CommOps or Modulartity. +* **Module** — A component can be broken down into multiple modules. Modules still share a single menu on the site, but their sources can be stored in different git repositories, even owned by different groups. The default module is called "ROOT" (that's what is in this example). If you don't want to use multiple modules, only use "ROOT". But to define more modules, simply duplicate the "ROOT" directory and name it anything you want. You can store modules in one or more git repositories. + +## Local preview + +This repo includes scripts to build and preview the contents of this repository. + +**NOTE**: Please note that if you reference pages from other repositoreis, such links will be broken in this local preview as it only builds this repository. If you want to rebuild the whole Fedora Docs site, please see [the Fedora Docs build repository](https://pagure.io/fedora-docs/docs-fp-o/) for instructions. + +Both scripts work on Fedora (using Podman) and macOS (using Docker). + +To build and preview the site, run: + +``` +$ ./build.sh && ./preview.sh +``` + +The result will be available at http://localhost:8080 + +### Installing Podman on Fedora + +Fedora Workstation doesn't come with Podman preinstalled by default — so you might need to install it using the following command: + +``` +$ sudo dnf install podman +``` + +### Preview as a part of the whole Fedora Docs site + +You can also build the whole Fedora Docs site locally to see your changes in the whole context. +This is especially useful for checking if your `xref` links work properly. + +To do this, you need to clone the main [Fedora Docs build repository](https://pagure.io/fedora-docs/docs-fp-o), modify the `site.yml` file to reference a repo with your changes, and build it. +Steps: + +Clone the main repository and cd into it: + +``` +$ git clone https://pagure.io/fedora-docs/docs-fp-o.git +$ cd docs-fp-o +``` + +Find a reference to the repository you're changing in the `site.yml` file, and change it so it points to your change. +So for example, if I made a modification to the Modularity docs, I would find: + +``` +... + - url: https://pagure.io/fedora-docs/modularity.git + branches: + - master +... +``` + +And replaced it with a pointer to my fork: +``` +... + - url: https://pagure.io/forks/asamalik/fedora-docs/modularity.git + branches: + - master +... +``` + +I could also point to a local repository, using `HEAD` as a branch to preview the what's changed without the need of making a commit. + +**Note:** I would need to move the repository under the `docs-fp-o` directory, because the builder won't see anything above. +So I would need to create a `repositories` directory in `docs-fp-o` and copy my repository into it. + +``` +... + - url: ./repositories/modularity + branches: + - HEAD +... +``` + +To build the whole site, I would run the following in the `docs-fp-o` directory. + +``` +$ ./build.sh && ./preview.sh +``` diff --git a/docs/antora.yml b/docs/antora.yml new file mode 100644 index 0000000..009c240 --- /dev/null +++ b/docs/antora.yml @@ -0,0 +1,16 @@ +# Name will be mostly visible in the URL. Treat it as an indentifier. +# Tip: If you want to use the local preview scripts that come with this repository, please change this value in the site.yml file as well. (under site/start_page) +name: websites + +# Title will be visible on the page. +title: Fedora Websites + +# If you don't plan to have multiple versions of the docs (for example, to document multiple versions of some software), you can ignore this field. Otherwise, change "master" to a specific version. +version: master + +# We encourage you to name the index page as "index.adoc". If you absolutely have to use a different name, please reflect it here. You can ignore this field otherwise. +start_page: ROOT:index + +# This lists all the menu definitions of your component. +nav: +- modules/ROOT/nav.adoc diff --git a/docs/build.sh b/docs/build.sh new file mode 100755 index 0000000..f4ecfe4 --- /dev/null +++ b/docs/build.sh @@ -0,0 +1,46 @@ +#!/bin/sh + +image="docker.io/antora/antora" +cmd="--html-url-extension-style=indexify site.yml" + +if [ "$(uname)" = "Darwin" ]; then + # Running on macOS. + # Let's assume that the user has the Docker CE installed + # which doesn't require a root password. + echo "" + echo "This build script is using Docker container runtime to run the build in an isolated environment." + echo "" + docker run --rm -it -v "$(pwd):/antora" $image $cmd + +elif [ "$(expr substr "$(uname -s)" 1 5)" = "Linux" ]; then + # Running on Linux. + # Check whether podman is available, else fall back to docker + # which requires root. + + if [ -f /usr/bin/podman ]; then + echo "" + echo "This build script is using Podman to run the build in an isolated environment." + echo "" + podman run --rm -it -v "$(pwd):/antora:z" $image $cmd + + elif [ -f /usr/bin/docker ]; then + echo "" + echo "This build script is using Docker to run the build in an isolated environment." + echo "" + + if groups | grep -wq "docker"; then + docker run --rm -it -v "$(pwd):/antora:z" $image $cmd + else + echo "" + echo "This build script is using $runtime to run the build in an isolated environment. You might be asked for your password." + echo "You can avoid this by adding your user to the 'docker' group, but be aware of the security implications. See https://docs.docker.com/install/linux/linux-postinstall/." + echo "" + sudo docker run --rm -it -v "$(pwd):/antora:z" $image $cmd + fi + else + echo "" + echo "Error: Container runtime haven't been found on your system. Fix it by:" + echo "$ sudo dnf install podman" + exit 1 + fi +fi diff --git a/docs/build/site.zip b/docs/build/site.zip new file mode 100644 index 0000000..1d1968e Binary files /dev/null and b/docs/build/site.zip differ diff --git a/docs/cache/ui/b23e735193edfbb6dbd32c30e386f682d5093c1c.zip b/docs/cache/ui/b23e735193edfbb6dbd32c30e386f682d5093c1c.zip new file mode 100644 index 0000000..9fd7b1b Binary files /dev/null and b/docs/cache/ui/b23e735193edfbb6dbd32c30e386f682d5093c1c.zip differ diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc new file mode 100644 index 0000000..6d0a691 --- /dev/null +++ b/docs/modules/ROOT/nav.adoc @@ -0,0 +1,6 @@ +* xref:setup-docker.adoc[Getting Set Up (Docker)] +* xref:setup.adoc[Getting Set Up (old method)] +* xref:fedora-release.adoc[Fedora Beta/GA Release] +* xref:newcontent.adoc[Creating New Content] +** xref:newcontent-edition.adoc[New Edition] +** xref:newcontent-site.adoc[New Site] diff --git a/docs/modules/ROOT/pages/fedora-release.adoc b/docs/modules/ROOT/pages/fedora-release.adoc new file mode 100644 index 0000000..2f9d521 --- /dev/null +++ b/docs/modules/ROOT/pages/fedora-release.adoc @@ -0,0 +1,126 @@ += Fedora Release +Rick Elrod +:page-authors: {author} + +== Introduction + +[NOTE] +==== +This assume you have a working setup already. See the other documents (e.g. the +one using Docker to get a development environment working) to get set up. Also, +if using a container-based environment, *ensure that the image you're using +reflects the latest `Dockerfile` in the root of the repository.* +==== + +This document guides you through updating the websites for a release (beta or +GA) of Fedora. + +Most of the work comes down to editing one file, +`sites/getfedora.org/release.yaml`. What follows are the important points to +note. + +The `release.yaml` file is broken into several main sections, and the relevant +ones are `ga`, `beta`, `fmw`, and `gpg_keys`. + +[NOTE] +==== +Pushing to the `staging` branch will update https://stg.getfedora.org/, which +pushing to the `master` branch will update https://getfedora.org/. +==== + +=== Beta Releases + +If you are updating for a *beta* release, then you are free to leave the `ga` +section alone. + +In the `beta` section, you'll want `show` to be `true`. This toggles whether we +show the beta download links at all. It also changes the banner at the top of +the website to announce the beta instead of the previous GA release. The +`announcement_release_number` dictates which version number is shown in that +announcement, so you'll want to bump it to the beta version being released. + +Next you'll want to edit the `editions` section, still under the `beta` parent +section. Bump the `release_number` and set the `rc_version` to the RC that was +called gold/ready for release. Find this information out from releng, if +necessary. + +== GA Releases + +If you are updating for a *ga* release, then in the `beta` section, set `show` +to `false`, so that the beta downloads don't show, and the announcement at the +top of the landing site reflects the new GA. Check with someone (usually Paul +Frields (`stickster` on IRC) to find the URL of the Fedora Magazine announcement +for the release, and set `announcement_url` to that, in the `ga` section. + +Next, bump the `release_number` and `rc_version` of each edition under +`editions`, using the `rc_version` that was declared gold/ready for +release. Find this information out from releng, if necessary. + +== `releases.json` file + +The next step is to produce the `releases.json` static file used by Fedora Media +Writer to produce its list of possible downloads. In the `fmw` section of +`release.yaml`, update the `releases_json` list to include the current non-EOL +versions of Fedora, including any current betas. If a version is in beta, set +the its `milestone` to `beta`. Otherwise set it to `final` or leave out the +field altogether. + +For example: + +[source,yaml] +---- +fmw: + ... + releases_json: + - version: 31 + milestone: beta + - version: 30 + - version: 29 +---- + +Once this is done, you'll need to actually generate the `releases.json` file. + +If using a containerized environment, you can do this from the root of the +repository (replacing `sudo docker` with `podman` if you use Podman): + +[source,bash] +---- +sudo docker run -it --rm -v "$(pwd):/opt/:z" fedora-websites python ./scripts/releases-json.py > sites/getfedora.org/static/releases.json +---- + +Otherwise, if you're not using a containerized environment, you can run the +script yourself after installing the `python-fedfind` package. From the root of +the repository: + +[source,bash] +---- +python3 sites/getfedora.org/scripts/releases-json.py > sites/getfedora.org/static/releases.json +---- + +Check that releases.json looks sane (it should look like a blob of JSON), then +move on. + +== Checksum Files + +You'll need to import the checksum files into +`sites/getfedora.org/static/checksums/`. To find out which checksums you need to +import, you can simply do a build of getfedora.org, and it will error out and +tell you what is missing. This is by design to ensure we don't miss a checksum +file. + +== GPG Keys + +Lastly, you'll want to add the latest GPG key information to `gpg_keys` in +`release.yaml`. Follow the pattern that is already there, and move any now-EOL +releases into the `obsolete` subsection. + +Import any new GPG keys into `sites/getfedora.org/static/keys/`, naming the file +`[short key id].txt` e.g. `57BBCCBA.txt`. + +== Conclusion + +That should be all. The old sites (namely spins, labs, alt, arm) which haven't +been ported to the new system need to be updated separately and are beyond the +scope of this document. + +Commit your changes, and they should auto-deploy within two hours at most. diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc new file mode 100644 index 0000000..cd940a4 --- /dev/null +++ b/docs/modules/ROOT/pages/index.adoc @@ -0,0 +1,93 @@ += Fedora Websites +Rick Elrod; Ryan Lerch +:page-authors: {author}, {author_2} + +== Who We Are +The Fedora Websites & Apps team works on the frontend and backend of Fedora's websites and web applications. +This team is a reboot of the previous Fedora Website's team, created by community members to update and improve Fedora's web presence and online documentation. + +We are a growing team of developers with a range of skills and interests. One of our team's first goals is to set up the foundation of an empowering mentorship program. + +== Our Collaborations +Working on both websites and web applications, our team is regularly communicating and working with different stakeholders in Fedora's community. + +* We work closely with the link:++https://fedoraproject.org/wiki/Design++[Fedora Design team] to build our websites that are visually pleasing, easy to use, and accessible to everybody. +* Along with the design team, we also work closely with link:++https://fedoraproject.org/wiki/Infrastructure++[Fedora Infrastructure] on backend technologies. +* We also collaborate with the link:++https://fedoraproject.org/wiki/L10N++[Fedora Translations team] to ensure that websites are able to be translated into different languages. +* Typically has one member (either in Design or Websites) who sits on the + xref:mindshare::index.adoc[Fedora Mindshare committee]. + +== What We Do +The W&A Team updates and maintains the code bases for Fedora's websites and web applications. We collaborate closely with the Fedora Design team and Fedora Infrastructure to implement new designs and update backend code. The W&A team is regularly working on a variety of tasks that are suitable for new and experienced contributors. + +=== Tasks Include: +* Adding temporary content to websites +* Coding design mockups provided by the Design Team +* Updating server side code +* Improving language and accessiblity support +* Revamping websites to improve user experience +* Writing documentation for contributors + +=== The Web and Apps Team Revamp +In 2021, the Fedora Websites Team began a revamp into the Fedora Websites & Apps Team. This was was started in order to facilitate the growing interest in Fedora's web presence as well as a need for a knowledgeable group of contributors to focus on keeping Fedora's websites and apps up to date current with modern web standards. + +== How To Get Involved + +To get involved with the Fedora W&A team get in touch with us through the email list or by messaging us on Telegram. We are looking for both front and backend contributors of all skill levels. If you are interested in getting active, feel free to check out the open tickets on pagure. + +We also welcome new contributors to our weekly meetings. If you have something that you would like to address, send a message to one of our team leads ahead of time so that we can plan to discuss your topic at an upcomming session. + +=== Membership + +In order to become a member of the Fedora Website & Apps Team, the applicant must be register at link:++https://accounts.fedoraproject.org++[Fedora Accounts] and set up an account with the link:++https://pagure.io++[Pagure] gitforge. + +By becoming a Fedora Contributor, you accept these terms. + +* link:++https://fedoraproject.org/wiki/Legal:Fedora_Project_Contributor_Agreement++[Fedora Project Contributor Agrement (FPCA)] +* link:++https://docs.fedoraproject.org/en-US/project/code-of-conduct/++[Code of Conduct] + +=== Are You New to Web Development? +We flag tickets that are suitable for new contributors and those whom are newer to html, css, js, and python. If you aren't sure where to start, or cannot find documentation that you are looking for, get in touch with one of our team members and they will help point you in the right direction. + +One of the goals of our revamp is to offer mentorship to those who are new to the field, or just interested in advancing their skills. If you are interested in mentorship, get in touch with one of our admins and they will help connect you with someone for mentorship opportunities. + +=== Are you an experienced Web Developer? +We often have tickets that demand more advanced knowledge of the technologies in our stack, and as web development is such a fast moving field, we are always interested to work with developers that bring something new to the table. Do you see something that you would like to work on? Please get in touch with us. + +== Meetings +We hold weekly meetings to review tickets and other tasks, touch base on direction, check in with one another, discuss team direction, and plan activities. Feel free to join us and get involved or to come and ask any questions that you have. We are a diverse team that is always looking for new contributors. + +* Location: link:++https://meet.jit.si/fedora-websites-apps-meeting++[Jitsi Room] +* Day: Tuesdays +* Time: 15:00 - 16:00 UTC + +=== Communication Channels +The W&A Team has a couple different lines of communication. Get in touch with us in any of the following ways (most being connected together): + +* link:++https://t.me/joinchat/hWQIgi7L79k3Nzk5++[Telegram]: Fedora Websites and Apps Telegram Group +* link:++https://discussion.fedoraproject.org/c/project/websites/66++[Discussion Forum]: Public Discussion Space +* link:++https://lists.fedoraproject.org/archives/list/websites@lists.fedoraproject.org/++[Email List]: Announcements, new member introductions +* link:++https://matrix.to/#/#fedora-websites:matrix.org++[Matrix]: Fedora Websites and Apps Matrix Channel +* link:++ircs://irc.libera.chat:6697/#fedora-websites++[IRC]: Fedora Websites and App IRC Channel + +== Resources +The W&A Team is made up of people who work on all levels of the tech stack. We value perspectives and experience from all positions of the tech stack. Check out these resources for your own setup. We are always working to expand our instructional material and documentation. + +=== Fedora's Website Tech Stacks +* Fedora Community Blog: Wordpress +* Fedora Websites: Flask, Jinja, HTML, CSS3, JavaScript, Python 3 +* Fedora Docs: Asciidoc + +=== Documentation +* link:++https://fedoraproject.org/w/uploads/1/19/Websitesandappsrevamp_logicmodel.png++[Fedora Websites Revamp Logic Model]: An overview of the Websites Team revamp +* link:++https://developer.fedoraproject.org/tech/languages/python/python-installation.html++[Fedora Developer Python] +* link:++https://developer.fedoraproject.org/tech/languages/python/flask-installation.html++[Fedora Developer Flask] +* For those interested in php and working with the link:++https://communityblog.fedoraproject.org++[Fedora Community Blog] +* link:++https://fedoramagazine.org/howto-install-wordpress-fedora/++[Wordpress Local Setup Instructions]: This article will help you setup a local wordpress deployment on Fedora. + +== Code Repositories +* link:++https://pagure.io/fedora-websites++[Fedora Websites] +* link:++https://pagure.io/fedora-web/websites/++[Fedora Main Website] +* link:++https://github.com/fedora-infra/fedbadges++[Fedora Badges] +* link:++https://github.com/fedora-infra/noggin++[Fedora Account System(FAS)] +* link:++https://pagure.io/fedora-docs/docs-fp-o++[Fedora Docs] diff --git a/docs/modules/ROOT/pages/newcontent-edition.adoc b/docs/modules/ROOT/pages/newcontent-edition.adoc new file mode 100644 index 0000000..f6fd5db --- /dev/null +++ b/docs/modules/ROOT/pages/newcontent-edition.adoc @@ -0,0 +1,89 @@ += New Edition +Rick Elrod +:page-authors: {author} + +== Introduction + +Fedora editions are "versions" of Fedora that users can install. These include +"official" editions (Workstation and Server at time of writing), but the +ultimate goal in Websites is to also make Spins and Labs editions be considered +"editions" in some form as far as websites are concerned. That is to say, we'd +like to ultimately have Spins and Labs have a section on the main getfedora.org +site, rendering link:https://spins.fedorparoject.org/[] and +link:https://labs.fedoraproject.org/[] useless and able to be gotten rid of. +Doing this effectively will take some time. + +Also note that most of the content in this document applies to adding pages in +general, with the notable exception of the `release.yaml` edits. Adding a page +to getfedora.org should follow largely the same process, though. + +[NOTE] +==== +All new editions should be added to getfedora.org, to aid in our goal of getting +rid of all of the `*.fedoraproject.org` edition-specific subdomain sites. This +generates a more consistent and less confusing user experience and makes +maintenance of the websites easier going forward. Everything in this document +assumes that you are working with the getfedora.org codebase, and NOT creating a +new site from scratch. +==== + +Now then, all work in this document takes place in the repository in which +link:https://pagure.io/fedora-web/websites/[getfedora.org] lives, and particularly +in the `sites/getfedora.org/` directory. + +== Edition-specific Release Variables + +The first step is to edit `release.yaml`, and add the relevant sections under +`ga` and `beta` for your new edition. Use `workstation` and `server` as +templates. You might not need all variables that these existing sections have, +or you might need to add new ones, depending on your templates, but these blocks +should get you started. + +== Exporting the Edition Routes + +Now, open `main.py` and go to near the bottom, where you'll note a number of +`export_route(...)` calls. This method is a custom method defined earlier in the +file, which does a little bit of work for us: The first argument is an internal +identifier name, so that we can reference the page using `url_for` safely (if +the URL changes, so will the URLs that get generated by `url_for`). The second +argument is a path to the directory that contains the templates you'll make, but +with a preceding and trailing `/`. Follow the example of the other, currently +existing pages and add the appropriate `export_route` calls at the end. + +== Hacking the Templates + +The templates themselves live in the `sites` directory (under +`sites/getfedora.org/` still). There are already templates started (but not +currently exported in `main.py`) for `silverblue`, `coreos`, and `iot`, at time +of writing. + +[IMPORTANT] +==== +Every string you add *must* be enclosed in `{% trans %}` ... `{% endtrans %}` +blocks so that it can be translated. If the string spans multiple lines (we tend +to break at 80 characters but are fairly lenient about this), then the opening +block should instead be `{% trans trimmed %}` (the closing block is still just +`{% endtrans %}`). +==== + +You can copy the templates from the existing editions, if you need inspiration +or help. + +== Letting the Translators Do Their Thing + +Once the above is done, the next step is get all the strings in the hands of the +Fedora Translations team. If you have an account on Fedora's Zanata instance, +and are in the appropriate websites group on Zanata, and have a valid +`~/.config/zanata.ini` file, you can do this step yourself. Otherwise you'll +either need to be added to the appropriate team or have someone do this for you: + +Run `./scripts/translations-source.sh`. At the end of its output, it will give +you the Zanata command to push the strings up: `zanata push getfedora.org.pot` + +== Concluding + +Largely, that is it. You've added variables that are easy to update each release +(in `release.yaml`), you've exported the pages, written your templates in a +translatable way, and pushed those strings to the Translations team. Now you can +sit back and relax while the translators do their thing. Their translations will +go live immediately (well, within an hour) and automatically. diff --git a/docs/modules/ROOT/pages/newcontent-site.adoc b/docs/modules/ROOT/pages/newcontent-site.adoc new file mode 100644 index 0000000..b468541 --- /dev/null +++ b/docs/modules/ROOT/pages/newcontent-site.adoc @@ -0,0 +1,15 @@ += Creating A New Site +Rick Elrod +:page-authors: {author} + +In rare cases, you might need to create an entirely new site, rather than an +edition or page on getfedora.org. + +In a future world, this document will help you do so. + +For this to happen effectively, we'll need to abstract some things out from the +current getfedora.org work. + +But familiarizing yourself with link:https://flask.palletsprojects.com/[Flask] +and link:https://pythonhosted.org/Frozen-Flask/[Frozen-Flask] is a good starting +point, as we plan for all of our websites to build using this toolset. diff --git a/docs/modules/ROOT/pages/newcontent.adoc b/docs/modules/ROOT/pages/newcontent.adoc new file mode 100644 index 0000000..b64ab51 --- /dev/null +++ b/docs/modules/ROOT/pages/newcontent.adoc @@ -0,0 +1,23 @@ += Creating New Content +Rick Elrod +:page-authors: {author} + +Content can be broken into several different components, although some of the +process is the same for all cases. + +All new sites are being built with the Python link:http://flask.pocoo.org/[Flask] +framework and the link:https://pythonhosted.org/Frozen-Flask/[Frozen-Flask] library +for generating static pages. + +== New Editions + +New editions of Fedora should be added to the getfedora.org website. We are +trying to get away from having a bunch of `*.fedoraproject.org` sites for each +of the various editions (currently we have link:https://coreos.fedoraproject.org[], +link:https://iot.fedoraproject.org[], etc.). + +== New Websites + +There are cases, however, where the content being added is *not* a new edition, +and is deserving of having its own distinct website, separate from +getfedora.org. These cases should probably be somewhat rare. diff --git a/docs/modules/ROOT/pages/setup-docker.adoc b/docs/modules/ROOT/pages/setup-docker.adoc new file mode 100644 index 0000000..4f927ef --- /dev/null +++ b/docs/modules/ROOT/pages/setup-docker.adoc @@ -0,0 +1,76 @@ += Getting Set Up (using Docker) +Rick Elrod +:page-authors: {author} + +== Preliminary Notes + +It is now easier to get started on developing the Fedora Websites with the use +of Docker (or Podman). + +We ship a `Dockerfile` which will install dependencies into an image +for you, so all you are left to do is mount the site as a volume, pull +translations, and start the development server. + +[NOTE] +==== +The documentation here refers to `docker`, but our fairly simple use +of it means that things are likely to work with `podman` with little +modification. +==== + +== Building the container image + +First clone the repository: + +[source,bash] +---- +git clone https://pagure.io/fedora-web/websites.git +---- + +(You may instead clone your fork of it, or add your fork as a second +remote later on.) + +Now ensure Docker is running and run: + +[source,bash] +---- +sudo docker build -t fedora-websites . +---- + +This will generate a container image for you to use. + +== Pulling translations + +We have a script for pulling translations. Let's call it from within +the container: + +[source,bash] +---- +sudo docker run -it --rm -v "$(pwd):/opt/:z" fedora-websites ./scripts/pull-translations.sh +---- + + +Notice here that we are mounting a volume (`-v`) in Docker which +points to our check-out of the repository. We're referring to the +`fedora-websites` image created above, and calling the +`./scripts/pull-translations.sh` script from within it. + +== Running the development server + +Now we are ready to run the development server: + +[source,bash] +---- +sudo docker run -it --rm -v "$(pwd):/opt/:z" -p 5000:5000 fedora-websites flask run --reload --host 0.0.0.0 +---- + +Note that we need `-p 5000:5000` so that we can access the development +server from our actual host. Also notice that we need to tell Flask to +listen on `0.0.0.0` as by default it listens on `127.0.0.1` which +won't be accessible outside of the container. + +You may now go to `http://localhost:5000/` in your browser of choice. + +Now you are ready to go and any changes you make in the repository +should be reflected immediately upon refreshing the page in your +browser. diff --git a/docs/modules/ROOT/pages/setup.adoc b/docs/modules/ROOT/pages/setup.adoc new file mode 100644 index 0000000..e715bf2 --- /dev/null +++ b/docs/modules/ROOT/pages/setup.adoc @@ -0,0 +1,103 @@ += Getting Set Up +Rick Elrod +:page-authors: {author} + +[NOTE] +==== +We now have documentation on using the `Dockerfile` which ships in the Fedora +websites repository, and suggest trying that method before using the method +outlined on this page. See link:../setup-docker[this tutorial]. +==== + +== Preliminary Notes + +There are some open tickets (https://pagure.io/fedora-web/websites/issue/31[31], +https://pagure.io/fedora-web/websites/issue/11[11]) about getting the websites +repository building on Fedora with Python 3. + +However, it should be able to be built on Fedora 30, using Python 2 packages, +for now. + +=== Fedora 29 Alternative + +Note, the dependencies below may not currently resolve due to package renaming +in Fedora 30. If the dependencies do not resolve in Fedora 30, running Flask +from a Fedora 29 container is an alternative. An example to run the Fedora 29 +container using `podman` is as follows: + +``` +# Expose the default port for Flask, 5000. +podman run --expose 5000 --net=host --privileged -v /path/to/websites/repo:/path/to/websites/repo -ti registry.fedoraproject.org/fedora:29 +``` + +== Dependencies + +That said, assuming Fedora 30, install the dependencies as follows +footnote:[This list comes directly from the Fedora Infrastructure OpenShift +build for Websites found +https://infrastructure.fedoraproject.org/cgit/ansible.git/tree/roles/openshift-apps/websites/templates/buildconfig.yml[here].]: + +[source,bash] +---- +dnf install \ + git \ + python-flask \ + python-frozen-flask \ + python-flask-assets \ + python-rjsmin \ + python-cssmin \ + python-flask-babel \ + python-flask-htmlmin \ + python-cssutils \ + rubygem-sass \ + babel \ + python3-jinja2 \ + python-pyyaml \ + python-dateutil \ + python-dogpile-cache \ + python-requests \ + python-zanata-client +---- + +== Pull Strings + +Now we need to pull the current translations. After installing the dependencies +above, you can `cd` into `sites/getfedora.org/` and run: +`./scripts/pull-translations.sh`. + +Once the dependencies are installed and translations are pulled, you can do one +of two things: + +== Use the Development Server + +One option is to use the Flask built-in development server. This is handy +because it prevents you from needing to build the websites every time you change +something. However, it bypasses the Frozen-Flask system which creates are static +sites, entirely, so it's not entirely an accurate representation of what goes +live. + +To use the development server: + +[source,bash] +---- +export FLASK_APP=main.py +flask run --reload +---- + +Now you many visit http://localhost:5000/ to get to the site. + +== Use Apache + +Alternatively, you may simply run `python main.py`. You'll get a statically +built site in the `./build/` directory. However, the HTML files are all +language-code-suffixed as Apache/httpd MultiViews system expects +(e.g. `index.html.en`). As a result you *cannot* just run a simple HTTP server +(like `python -m SimpleHTTPServer`) in the `./build/` directory, unfortunately. + +You can, however, set up an Apache on your system, and point it to the +`./build/` directory. + +[NOTE] +==== +(We should probably add an example Apache config here at some point). +==== diff --git a/docs/modules/ROOT/pages/translation-flow.adoc b/docs/modules/ROOT/pages/translation-flow.adoc new file mode 100644 index 0000000..c017809 --- /dev/null +++ b/docs/modules/ROOT/pages/translation-flow.adoc @@ -0,0 +1,85 @@ += Translation flow (for Fedora websites) + Jan Kuparinen +:page-authors: {author} + +== General + +Fedora websites can be viewed in many languages. This page gives some details on how this happens. + +=== Tagging text + +System needs to be told what strings needs to be translated. +Generally every text inside web page should be surrounded with tags: + +[source,html] +---- +{% trans trimmed %}Translate this text.{% endtrans %} +---- + +== Generating pot file +First we need to pull all translatable strings into a file called getfedora.org.pot + +This file is generated by running: + +[source,bash] +---- +podman run -it --rm -v "$(pwd):/opt/:z" fedora-websites ./scripts/translations-source.sh +---- + +This file needs to be sent to link:++https://pagure.io/fedora-web/translations++[translations repository] + +If you don't have access to the translations repository push it to fedora-websites and create a pull request and once approved it should be automatically sent to translations repository with 24 hours. + +== Weblate process (How strings get translated) + +Once getfedora.org.pot file is in the translations repository it will be pulled by Weblate system and merged into translatable strings. It can then be translated by translators. + +== Manual testing +[NOTE] +==== +Any translations made here will not get propagated to the weblate of final versions of the page. +==== +You can test the changes manually by: + +1) +Update strings to the language files +[source,bash] +---- +podman run -it --rm -v "$(pwd):/opt/:z" fedora-websites ./scripts/translations-update-local.sh +---- + +Now edit desired language file, for example + +[source,bash] +---- +nano sites/getfedora.org/translations/fi/LC_MESSAGES/messages.po +---- +Find the string you want to test, format inside file is: + + `#: partials/templates/download_card.html:13` Location(s) of string. + `msgid "Download"` Text in english. + `msgstr "Lataa"` Text in desired language. + + +Edit the `msgstr` + +Once edited translations need to be compiled into more efficient format for the web server. This is done by running: + +[source,bash] +---- +podman run -it --rm -v "$(pwd):/opt/:z" fedora-websites ./scripts/translations-compile-local.sh +---- + +You can now change your browser setting to desired language and see how the translations are working out. + +--- + +=== Description of translation scripts inside sites/getfedora.org/scripts + +[NOTE] +==== +Technically scripts can be run without using podman, but will then require proper setup in the local machine. The instructions given above are safer for generic users. +==== + + + diff --git a/docs/nginx.conf b/docs/nginx.conf new file mode 100644 index 0000000..f7093b3 --- /dev/null +++ b/docs/nginx.conf @@ -0,0 +1,14 @@ +server { + listen 80; + server_name localhost; + + location / { + root /antora/public; + index index.html index.htm; + } + + error_page 500 502 503 504 /50x.html; + location = /50x.html { + root /usr/share/nginx/html; + } +} diff --git a/docs/preview.sh b/docs/preview.sh new file mode 100755 index 0000000..4270107 --- /dev/null +++ b/docs/preview.sh @@ -0,0 +1,18 @@ +#!/bin/sh + +if [ "$(uname)" = "Darwin" ]; then + # Running on macOS. + # Let's assume that the user has the Docker CE installed + # which doesn't require a root password. + echo "The preview will be available at http://localhost:8080/" + docker run --rm -v "$(pwd):/antora:ro" -v "$(pwd)/nginx.conf:/etc/nginx/conf.d/default.conf:ro" -p 8080:80 nginx + +elif [ "$(expr substr "$(uname -s)" 1 5)" = "Linux" ]; then + # Running on Linux. + # Fedora Workstation has python3 installed as a default, so using that + echo "" + echo "The preview is available at http://localhost:8080" + echo "" + cd ./public + python3 -m http.server 8080 +fi diff --git a/docs/public/_/css/site.css b/docs/public/_/css/site.css new file mode 100644 index 0000000..b4b1990 --- /dev/null +++ b/docs/public/_/css/site.css @@ -0,0 +1,3 @@ +@font-face{font-family:Roboto;font-style:normal;font-weight:400;src:local("Roboto Regular"),local("Roboto-Regular"),url(../font/roboto-latin-400.woff2) format("woff2"),url(../font/roboto-latin-400.woff) format("woff")}@font-face{font-family:Roboto;font-style:italic;font-weight:400;src:local("Roboto Italic"),local("Roboto-Italic"),url(../font/roboto-latin-400italic.woff2) format("woff2"),url(../font/roboto-latin-400italic.woff) format("woff")}@font-face{font-family:Roboto;font-style:normal;font-weight:500;src:local("Roboto Medium"),local("Roboto-Medium"),url(../font/roboto-latin-500.woff2) format("woff2"),url(../font/roboto-latin-500.woff) format("woff")}@font-face{font-family:Roboto;font-style:italic;font-weight:500;src:local("Roboto Medium Italic"),local("Roboto-MediumItalic"),url(../font/roboto-latin-500italic.woff2) format("woff2"),url(../font/roboto-latin-500italic.woff) format("woff")}@font-face{font-family:Roboto Mono;font-style:normal;font-weight:400;src:local("Roboto Mono"),local("RobotoMono-Regular"),url(../font/roboto-mono-latin-400.woff2) format("woff2"),url(../font/roboto-mono-latin-400.woff) format("woff")}@font-face{font-family:Roboto Mono;font-style:normal;font-weight:500;src:local("Roboto Mono Medium"),local("RobotoMono-Medium"),url(../font/roboto-mono-latin-500.woff2) format("woff2"),url(../font/roboto-mono-latin-500.woff) format("woff")}body,html{height:100%}*,:after,:before{-webkit-box-sizing:inherit;box-sizing:inherit}html{-webkit-box-sizing:border-box;box-sizing:border-box;font-family:Roboto,sans-serif;font-size:1.1em;-webkit-text-size-adjust:100%;-moz-text-size-adjust:100%;-ms-text-size-adjust:100%;text-size-adjust:100%}@media (min-width:1024px){html{font-size:1.2em}}body{color:#222;line-height:1.6;margin:0}@media print{body{padding-top:0!important}nav.navbar{position:static!important}}a{text-decoration:none}a:hover{text-decoration:underline}code,kbd,pre{font-family:Roboto Mono,monospace}b,dt,strong,th{font-weight:700}::-webkit-scrollbar{width:.3333rem;height:.3333rem}::-webkit-scrollbar-track{background-color:#f0f0f0}::-webkit-scrollbar-thumb{background-color:#c1c1c1}::-webkit-scrollbar-thumb:window-inactive{background:transparent}@media (min-width:1024px){.main-wrapper{display:-webkit-box;display:-ms-flexbox;display:flex}.main{-webkit-box-flex:1;-ms-flex:auto;flex:auto;min-width:0}}.navigation-container{display:none;position:fixed;top:3.25rem;left:0;width:100%;font-size:.95rem;z-index:1}.navigation-container.is-active{display:block}@media (min-width:769px){.navigation-container{width:16rem;font-size:.9rem}}@media (min-width:1024px){.navigation-container{font-size:.85rem;-webkit-box-flex:0;-ms-flex:none;flex:none;display:block;position:static;top:0}}.navigation{background-color:#fafafa;position:relative;top:30px;height:calc(100vh - 3.25rem - 30px)}@media (min-width:769px){.navigation{-webkit-box-shadow:.5px 0 3px #c1c1c1;box-shadow:.5px 0 3px #c1c1c1}}@media (min-width:1024px){.navigation{top:3.25rem;-webkit-box-shadow:none;box-shadow:none;position:-webkit-sticky;position:sticky;height:calc(100vh - 3.25rem)}}.navigation .panels{display:-webkit-box;display:-ms-flexbox;display:flex;-webkit-box-orient:vertical;-webkit-box-direction:normal;-ms-flex-direction:column;flex-direction:column;height:inherit}html.is-clipped--nav{overflow-y:hidden}.navigation-menu{-webkit-box-flex:1;-ms-flex-positive:1;flex-grow:1;overflow-y:auto;display:-webkit-box;display:-ms-flexbox;display:flex;-webkit-box-orient:vertical;-webkit-box-direction:normal;-ms-flex-direction:column;flex-direction:column;height:calc(100vh - 3.25rem - 30px - 2.5rem)}@media (min-width:1024px){.navigation-menu{height:calc(100vh - 5.75rem)}}.navigation-menu:not(.is-active){display:none}.navigation-container,.navigation-menu{background-color:#dedede}.nav-menu{-webkit-box-flex:1;-ms-flex-positive:1;flex-grow:1;min-height:0}nav.nav-menu span.nav-text strong{text-transform:uppercase;display:block;color:#294172;margin-top:16px;font-size:.9em}.nav-menu h3.title{margin:0;font-weight:500;color:#424242;font-size:1em;padding:.125rem .5rem .25rem}.nav-menu a,.nav-menu a:visited{color:inherit}.nav-list{margin:0;padding:0 0 .5em;width:100%}.nav-list .nav-list{margin-left:1em;padding-bottom:0}.nav-item{display:-webkit-box;display:-ms-flexbox;display:flex;-webkit-box-align:start;-ms-flex-align:start;align-items:flex-start;-ms-flex-wrap:wrap;flex-wrap:wrap;list-style:none;padding-top:5px;padding-bottom:5px}ul.nav-list .nav-item .is-current-page,ul.nav-list .nav-item .is-current-path{background-color:#fff}ul.nav-list ul.nav-list .nav-item{padding-left:10px}.nav-menu .title a{margin-left:20px}.nav-item:not(.is-active)>.nav-list{display:none}.nav-item[data-depth="0"]>.nav-list:first-child{display:block;margin-left:0}.nav-item[data-depth="0"]>.nav-list:first-child>.nav-item:first-child{padding-top:0}.nav-toggle{background:transparent url(../img/caret.svg) no-repeat 0;background-size:85%;border:none;cursor:pointer;height:1.85em;outline:none;padding:0;font-size:.95em;width:1.0526em}@media (min-width:769px){.nav-toggle{height:1.6em}}.nav-toggle::-moz-focus-inner{border:none}.nav-item.is-active>.nav-toggle{-webkit-transform:rotate(90deg);transform:rotate(90deg)}.nav-link,.nav-text{display:inline-block;line-height:1.85;margin-left:1em;padding-left:.25em}@media (min-width:769px){.nav-link,.nav-text{line-height:1.6}}.is-current-page>.nav-link,.is-current-page>.nav-text{font-weight:700}.nav-toggle+.nav-link,.nav-toggle+.nav-text{margin-left:0}.navigation-explore{display:-webkit-box;display:-ms-flexbox;display:flex;-webkit-box-orient:vertical;-webkit-box-direction:normal;-ms-flex-direction:column;flex-direction:column}.navigation-explore.is-active{height:inherit}.navigation-explore .context{-ms-flex-negative:0;flex-shrink:0;color:#5d5d5d;background-color:#fafafa;-webkit-box-shadow:0 -1px 0 #e1e1e1;box-shadow:0 -1px 0 #e1e1e1;padding:0 .25rem 0 .5rem;display:-webkit-box;display:-ms-flexbox;display:flex;-webkit-box-align:center;-ms-flex-align:center;align-items:center;-webkit-box-pack:justify;-ms-flex-pack:justify;justify-content:space-between;cursor:pointer;font-size:.8824em;line-height:1;height:2.5rem}.navigation-explore.is-active .context{-webkit-box-shadow:0 1px 0 #e1e1e1;box-shadow:0 1px 0 #e1e1e1}.navigation-explore .context .version{background-image:url(../img/chevron.svg);background-repeat:no-repeat;background-position:right .5rem top 50%;background-size:auto .75em;padding:0 1.5rem 0 0}.navigation-explore .components{-webkit-box-flex:1;-ms-flex-positive:1;flex-grow:1;-webkit-box-shadow:inset 0 1px 5px #e1e1e1;box-shadow:inset 0 1px 5px #e1e1e1;background-color:#f0f0f0;padding:.5rem;margin:0;overflow-y:auto;max-height:100%;display:block}.navigation-explore:not(.is-active) .components{display:none}.navigation-explore .component{display:block}.navigation-explore .component+.component{margin-top:.5rem}.navigation-explore .component .title{font-weight:500}.navigation-explore .versions{display:-webkit-box;display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;list-style:none;padding-left:.5rem}.navigation-explore .component .version{display:block;font-size:.95em}.navigation-explore .component .version a{border:1px solid #b0b0b0;border-radius:.25em;color:#4a4a4a;white-space:nowrap;padding:.05em .25em 0}.navigation-explore .component .is-current a{border-color:#4a4a4a;font-weight:500}.navigation-explore .component .version+.version{padding-left:.375em}.toolbar{color:#5d5d5d;-webkit-box-align:center;-ms-flex-align:center;align-items:center;background-color:#eee;display:-webkit-box;display:-ms-flexbox;display:flex;font-size:.75rem;height:30px;-webkit-box-pack:start;-ms-flex-pack:start;justify-content:flex-start;position:-webkit-sticky;position:sticky;top:3.22rem;z-index:1;padding:5px 15px}.toolbar a,.toolbar a:visited{color:inherit}.navigation-toggle{background:url(../img/menu.svg) no-repeat 50% 47.5%;background-size:49%;border:none;outline:none;cursor:pointer;display:block;height:2.5rem;padding:0;width:2.5rem;margin-right:-.25rem}.navigation-toggle::-moz-focus-inner{border:none}@media (min-width:1024px){.navigation-toggle{display:none}}.navigation-toggle.is-active{background-image:url(../img/back.svg);background-size:41.5%}.home-link{background:url(../img/home-o.svg) no-repeat 50% 45%;background-size:50%;display:block;height:2.5rem;padding:0;width:2.5rem}.home-link.is-current,.home-link:hover{background-image:url(../img/home.svg)}.edit-this-page{display:none;padding-right:.5rem}@media (min-width:1024px){.edit-this-page{display:block}}.toolbar .edit-this-page a{color:#8e8e8e}.crumbs{display:none;-webkit-box-flex:1;-ms-flex:1 1;flex:1 1;padding:0 .5rem 0 .75rem;line-height:1.35;-webkit-hyphens:none;-ms-hyphens:none;hyphens:none}@media (min-width:1024px){.crumbs{display:block}}a+.crumbs{padding-left:.05rem}.crumbs ul{display:-webkit-box;display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap;margin:0;padding:0;list-style:none;color:#0275d8}.crumbs li{display:inline;margin:0}.crumbs li:after{content:"/";color:#333;padding:0 .5rem}.crumbs li:last-of-type:after{content:none}.page-versions{display:none;margin-right:.7rem;position:relative}@media (min-width:1024px){.page-versions{display:block}}.page-versions.is-active{color:#333}.page-versions .versions-menu-toggle{color:inherit;font-family:inherit;font-size:inherit;background:url(../img/chevron.svg) no-repeat;background-position:right .5rem top 50%;background-size:auto .75em;border:1px solid transparent;outline:none;cursor:pointer;padding:.35rem 1.5rem .35rem .5rem;position:relative;z-index:1}.page-versions .versions-menu-toggle::-moz-focus-inner{border:none}.page-versions .versions-menu{border:1px solid transparent;background-color:#f0f0f0;padding:1.3rem .5rem .35rem;position:absolute;top:0;left:0;width:100%}.page-versions:not(.is-active) .versions-menu{display:none}.page-versions .version{display:block;line-height:1;padding-top:.6em}.page-versions .version.is-current{display:none}.page-versions .version.is-missing{color:#8e8e8e;font-style:italic;text-decoration:none}.doc{margin:0 auto;max-width:40rem;padding:0 1rem 4rem;color:#333}@media (min-width:1024px){.doc{margin:0 2rem;max-width:54rem}}.toc .title{font-family:Open sans,Helvetica,Arial;font-size:24px;color:#191919;font-weight:600}.doc h1,.doc h2,.doc h3,.doc h4,.doc h5,.doc h6{color:#191919;font-weight:600;line-height:1.3;margin:1rem 0 0}article.doc h1{font-weight:600;color:#294172!important}.doc h3,article.doc h1,ul.nav-list{font-family:Open sans,Helvetica,Arial}.doc h3{font-size:24px}.doc h1>a.anchor,.doc h2>a.anchor,.doc h3>a.anchor,.doc h4>a.anchor,.doc h5>a.anchor,.doc h6>a.anchor{position:absolute;text-decoration:none;width:1.75ex;margin-left:-1.5ex;visibility:hidden;font-size:.8em;font-weight:400;padding-top:.05em}.doc h1>a.anchor:before,.doc h2>a.anchor:before,.doc h3>a.anchor:before,.doc h4>a.anchor:before,.doc h5>a.anchor:before,.doc h6>a.anchor:before{content:"\00a7"}.doc h1:hover>a.anchor,.doc h2:hover>a.anchor,.doc h3:hover>a.anchor,.doc h4:hover>a.anchor,.doc h5:hover>a.anchor,.doc h6:hover>a.anchor{visibility:visible}.doc a,.doc a:visited{color:#1565c0}.doc a:hover{color:#104d92}.doc i.fa{font-style:normal}.doc p code{font-size:.9em;background-color:#fafafa;padding:.075rem .25rem .125rem;border-radius:.2rem;color:#d14}.doc pre{font-size:.9rem;line-height:1.5;margin:0}.doc .colist,.doc .dlist,.doc .exampleblock,.doc .imageblock,.doc .listingblock,.doc .literalblock,.doc .olist,.doc .paragraph,.doc .sidebarblock,.doc .ulist{margin:1rem 0 0}@media (min-width:1024px){.doc .sidebarblock.width50{width:54%}.doc .sidebarblock.width33,.doc .sidebarblock.width50{float:right;margin:0 -20px 0 20px;border:20px solid #fff}.doc .sidebarblock.width33{width:39%}}.doc table.tableblock{border-collapse:collapse;font-size:.8em;margin:2rem 0}.doc table.spread{width:100%}.doc table.tableblock td,.doc table.tableblock th{padding:.5rem}.doc table.tableblock th{border-bottom:2.5px solid #ddd}.doc table.tableblock td{border-top:1px solid #ddd;border-bottom:1px solid #ddd}.doc .halign-left{text-align:left}.doc .valign-top{vertical-align:top}.doc .tableblock p{font-size:inherit}.doc .admonitionblock{margin:1.4rem 0 0}.doc .admonitionblock p,.doc .admonitionblock td.content{font-size:.9rem}.doc .admonitionblock td.content>:first-child{margin:0}.doc .admonitionblock pre{font-size:.85rem}.doc .admonitionblock>table{border-collapse:collapse;table-layout:fixed;position:relative;width:100%}.doc .admonitionblock td.content{padding:1rem 1rem .75rem;background-color:#fafafa;width:100%}.doc .admonitionblock .icon{position:absolute;top:0;left:0;font-size:.75rem;padding:0 .5rem;height:1.25rem;line-height:1;font-weight:500;text-transform:uppercase;border-radius:.45rem;color:#fff;-webkit-transform:translate(-.5rem,-50%);transform:translate(-.5rem,-50%)}.doc .admonitionblock.caution .icon{background-color:#a0439c}.doc .admonitionblock.important .icon{background-color:#d32f2f}.doc .admonitionblock.note .icon{background-color:#217ee7}.doc .admonitionblock.tip .icon{background-color:#41af46}.doc .admonitionblock.warning .icon{background-color:#e18114}.doc .admonitionblock.caution td.content{border:1px solid #a0439c}.doc .admonitionblock.important td.content{border:1px solid #d32f2f}.doc .admonitionblock.note td.content{border:1px solid #217ee7}.doc .admonitionblock.tip td.content{border:1px solid #41af46}.doc .admonitionblock.warning td.content{border:1px solid #e18114}.doc .admonitionblock .icon i{display:-webkit-inline-box;display:-ms-inline-flexbox;display:inline-flex;-webkit-box-align:center;-ms-flex-align:center;align-items:center;height:100%}.doc .admonitionblock .icon i:after{content:attr(title);-webkit-hyphens:none;-ms-hyphens:none;hyphens:none}.doc .imageblock{display:-webkit-box;display:-ms-flexbox;display:flex;-webkit-box-orient:vertical;-webkit-box-direction:normal;-ms-flex-direction:column;flex-direction:column;-webkit-box-align:center;-ms-flex-align:center;align-items:center}.doc .imageblock img{display:block}.doc .imageblock .title{color:#191919;font-style:italic;margin-top:.5rem}.doc .imageblock img,.doc .paragraph .image img{height:auto;max-width:100%}.doc>h1{font-size:2rem;margin:2rem 0 1.5rem}#preamble+.sect1,.doc .sect1+.sect1{margin-top:2.5rem}.doc h2:not(.discrete){border-bottom:1px solid #ddd;margin-left:-1rem;margin-right:-1rem;padding:.4rem 1.5rem .1rem;font-size:36px;font-weight:600;font-family:Open sans,Helvetica,Arial}article.doc h2{border-bottom:solid #0275d8!important;padding:.4rem .9rem .1rem!important}.doc p{font-size:18px;margin:0}.doc .content,.doc .tableblock,.doc p{-webkit-hyphens:auto;-ms-hyphens:auto;hyphens:auto}#preamble .abstract blockquote{background-color:#f0f0f0;border-left:5px solid #ddd;color:#4a4a4a;font-size:.9em;margin:0;padding:.75em 1em}.doc table.tableblock .paragraph{margin:0;padding:0}.doc .olist .admonitionblock,.doc .ulist .admonitionblock,.doc table.tableblock .admonitionblock{padding:0}.doc ul{margin:0;padding:0 0 0 1.5rem}.doc ol{margin:0;padding:0 0 0 2rem;list-style:none;counter-reset:a}.doc ol>li{counter-increment:a}.doc ol>li:before{font-weight:500;font-size:.95em;display:inline-block;width:1em;direction:rtl;margin:-.025em .5em 0 -1.5em;text-align:right;position:absolute}.doc ol.arabic>li:before{content:"." counter(a)}.doc ol.loweralpha>li:before{content:"." counter(a,lower-alpha)}.doc ol.lowergreek>li:before{content:"." counter(a,lower-greek)}.doc ol.lowerroman>li:before{content:"." counter(a,lower-roman)}.doc ol.upperalpha>li:before{content:"." counter(a,upper-alpha)}.doc ol.upperroman>li:before{content:"." counter(a,upper-roman)}.doc ul.checklist{padding-left:.5rem;list-style:none}.doc ul.checklist p>i.fa-check-square-o:first-child,.doc ul.checklist p>i.fa-square-o:first-child{display:-webkit-inline-box;display:-ms-inline-flexbox;display:inline-flex;-webkit-box-pack:center;-ms-flex-pack:center;justify-content:center;width:1rem;margin-right:.25rem}.doc ul.checklist i.fa-check-square-o:before{content:"\2713"}.doc ul.checklist i.fa-square-o:before{content:"\274f"}.doc .dlist .dlist,.doc .dlist .olist,.doc .dlist .ulist,.doc .olist .dlist,.doc .olist .olist,.doc .olist .ulist,.doc .ulist .dlist,.doc .ulist .olist,.doc .ulist .ulist{margin-top:.5rem}.doc .olist li,.doc .ulist li{margin-bottom:.5rem}.doc .admonitionblock .listingblock,.doc .olist .listingblock,.doc .ulist .listingblock{padding:0}.doc .admonitionblock .title,.doc .exampleblock .title,.doc .listingblock .title,.doc .literalblock .title,.doc .openblock .title{color:#191919;font-size:.925rem;font-style:italic;letter-spacing:-.005em;padding-bottom:.075rem}.doc .admonitionblock .title+.paragraph{margin-top:0}.doc .exampleblock>.content{background-color:#fff;-webkit-box-shadow:inset 0 0 1.75px #248232;box-shadow:inset 0 0 1.75px #248232;padding:.75rem}.doc .exampleblock>.content>:first-child{margin-top:0}.doc .sidebarblock{background-color:#ebebeb;padding:.75rem 1.5rem}.doc .sidebarblock>.content>.title{color:#191919;font-size:1.2rem;font-weight:500;line-height:1.3;text-align:center}.doc .sidebarblock>.content>:not(.title):first-child{margin-top:0}.doc .listingblock.wrap pre,.doc .tableblock pre{white-space:pre-wrap}.doc pre.highlight code,.doc pre:not(.highlight){background-color:#fafafa;-webkit-box-shadow:inset 0 0 1.75px #ddd;box-shadow:inset 0 0 1.75px #ddd;display:block;overflow-x:auto;padding:.75rem}.doc pre.highlight{position:relative}.doc .listingblock code[data-lang]:before{content:attr(data-lang);display:none;color:#8e8e8e;font-size:.75em;font-weight:500;letter-spacing:.075em;line-height:1;text-transform:uppercase;position:absolute;top:.5rem;right:.5rem}.doc .listingblock:hover code[data-lang]:before{display:block}.doc .dlist dt{color:#4a4a4a;font-style:italic}.doc .dlist dd{margin:0 0 .3rem 1.5rem}.doc .conum[data-value]{border:1px solid #404040;border-radius:100%;display:inline-block;font-family:Roboto,sans-serif;font-size:.75rem;font-style:normal;height:1.25em;line-height:1.2;text-align:center;width:1.25em;letter-spacing:-.25ex;text-indent:-.25ex}.doc .conum[data-value]:after{content:attr(data-value)}.doc .conum[data-value]+b{display:none}.doc .colist{font-size:.95rem}.doc .colist>table tr>td:first-of-type{padding:0 .75em;line-height:1}b.button{white-space:nowrap}b.button:before{content:"[";padding-right:.25em}b.button:after{content:"]";padding-left:.25em}kbd{display:inline-block;font-size:.7rem;background-color:#fafafa;border:1px solid #c1c1c1;border-radius:.25em;-webkit-box-shadow:0 1px 0 #c1c1c1,0 0 0 .1em #fff inset;box-shadow:0 1px 0 #c1c1c1,inset 0 0 0 .1em #fff;padding:.25em .5em;vertical-align:text-bottom;white-space:nowrap}.keyseq,kbd{line-height:1}.keyseq{font-family:Roboto Mono,monospace;font-size:.9em}.keyseq kbd{margin:0 .125em}.keyseq kbd:first-child{margin-left:0}.keyseq kbd:last-child{margin-right:0}.menuseq i.caret:before{content:">";font-weight:500}.qanda li p:first-child{font-weight:600;margin-top:20px;margin-left:-20px}.imageblock.profile-picture{float:right;margin-left:30px;width:140px}.imageblock.profile-picture img{border-radius:8px}html.is-clipped--navbar{overflow-y:hidden}body{padding-top:3.25rem}.navbar{background-image:-webkit-gradient(linear,left top,left bottom,from(#eee),to(#ddd));background-image:linear-gradient(180deg,#eee 0,#ddd);color:#222;font-size:.83333rem;height:3.25rem;position:fixed;top:0;width:100%;word-wrap:break-word;z-index:2}.navbar a{text-decoration:none}.navbar-brand .navbar-item:first-child,.navbar-brand .navbar-item:first-child a{color:#222;font-size:1.15rem}.navbar-brand .separator{padding:0 .375rem}@media screen and (min-width:1024px){.navbar-end .navbar-link,.navbar-end>.navbar-item{color:#222}.navbar-end .navbar-link:hover,.navbar-end>a.navbar-item:hover{background-color:#ccc;color:#222}.navbar-end .navbar-link:after{border-color:#222}.navbar-item.has-dropdown:hover .navbar-link{background-color:#ccc;color:#222}}.navbar-brand{-webkit-box-align:stretch;-ms-flex-align:stretch;align-items:stretch;display:-webkit-box;display:-ms-flexbox;display:flex;-ms-flex-negative:0;flex-shrink:0;height:3.25rem}.navbar-burger{color:#222;background:none;border:none;outline:none;cursor:pointer;display:block;height:3.25rem;position:relative;width:2.75rem;margin-left:auto;padding:0}.navbar-burger::-moz-focus-inner{border:none}.navbar-burger span{background-color:#222;display:block;height:1px;left:50%;margin-left:-7px;position:absolute;top:50%;width:15px}.navbar-burger span:first-child{margin-top:-6px}.navbar-burger span:nth-child(2){margin-top:-1px}.navbar-burger span:nth-child(3){margin-top:4px}.navbar-burger.is-active span:first-child{margin-left:-5px;-webkit-transform:rotate(45deg);transform:rotate(45deg);-webkit-transform-origin:left top;transform-origin:left top}.navbar-burger.is-active span:nth-child(2){opacity:0}.navbar-burger.is-active span:nth-child(3){margin-left:-5px;-webkit-transform:rotate(-45deg);transform:rotate(-45deg);-webkit-transform-origin:left bottom;transform-origin:left bottom}.navbar-menu{display:none}.navbar-item,.navbar-link{color:#222;display:block;line-height:1.5;padding:.5rem 1rem;position:relative}.navbar-item{-webkit-box-flex:0;-ms-flex:none;flex:none}.navbar-item.has-dropdown{padding:0}.navbar-item .icon{width:1.1rem;height:1.1rem;display:block}.navbar-link{padding-right:2.5em}.navbar-dropdown{font-size:.875rem}.navbar-dropdown .navbar-item{padding-left:1.5rem;padding-right:1.5rem}.navbar-divider{background-color:#e1e1e1;border:none;height:1px;margin:.25rem 0}@media screen and (max-width:1023px){.navbar-brand .navbar-item{-webkit-box-align:center;-ms-flex-align:center;align-items:center;display:-webkit-box;display:-ms-flexbox;display:flex}.navbar-menu{background-color:#fff;padding:.5rem 0}.navbar-menu.is-active{display:block;-webkit-box-shadow:0 8px 16px hsla(0,0%,4%,.1);box-shadow:0 8px 16px hsla(0,0%,4%,.1);max-height:calc(100vh - 3.25rem);overflow-y:auto}.navbar-menu .navbar-link:hover,.navbar-menu a.navbar-item:hover{background-color:#fafafa}}@media screen and (min-width:1024px){.navbar,.navbar-end,.navbar-menu{-webkit-box-align:stretch;-ms-flex-align:stretch;align-items:stretch;display:-webkit-box;display:-ms-flexbox;display:flex}.navbar-burger{display:none}.navbar-item,.navbar-link{-webkit-box-align:center;-ms-flex-align:center;align-items:center;display:-webkit-box;display:-ms-flexbox;display:flex}.navbar-item.has-dropdown{-webkit-box-align:stretch;-ms-flex-align:stretch;align-items:stretch}.navbar-item.is-hoverable:hover .navbar-dropdown{display:block}.navbar-link:after{border-width:0 0 1px 1px;border-style:solid;content:" ";display:block;height:.5em;pointer-events:none;position:absolute;-webkit-transform:rotate(-45deg);transform:rotate(-45deg);width:.5em;margin-top:-.375em;right:1.125em;top:50%}.navbar-menu{-webkit-box-flex:1;-ms-flex-positive:1;flex-grow:1}.navbar-end{-webkit-box-pack:end;-ms-flex-pack:end;justify-content:flex-end;margin-left:auto}.navbar-dropdown{background-color:#fff;border:1px solid #e1e1e1;display:none;font-size:.875rem;top:100%;left:0;min-width:100%;position:absolute}.navbar-dropdown .navbar-item{padding:.5rem 1rem;white-space:nowrap}.navbar-dropdown a.navbar-item{padding-right:3rem}.navbar-dropdown.is-right{left:auto;right:0}.navbar-dropdown a.navbar-item:hover{background-color:#fafafa}}.navbar .button{display:-webkit-inline-box;display:-ms-inline-flexbox;display:inline-flex;-webkit-box-align:center;-ms-flex-align:center;align-items:center;background-color:#fff;border:1px solid #e1e1e1;border-radius:.15rem;height:1.75rem;color:#333;padding:0 .75em;white-space:nowrap}footer.footer{font-size:.85rem;background-color:#e6e6e6;color:#8e8e8e;padding:.5rem 1rem}.footer p{margin:.5rem 0;font-size:17px;color:#8d8d8d;font-family:Open sans,Helvetica,Arial}.footer a{color:#5d5d5d} + +/*! GitHub style for highlight.js (c) Vasily Polovnyov */.hljs-comment,.hljs-quote{color:#998;font-style:italic}.hljs-keyword,.hljs-selector-tag,.hljs-subst{color:#333;font-weight:500}.hljs-literal,.hljs-number,.hljs-tag .hljs-attr,.hljs-template-variable,.hljs-variable{color:teal}.hljs-doctag,.hljs-string{color:#d14}.hljs-section,.hljs-selector-id,.hljs-title{color:#900;font-weight:500}.hljs-subst{font-weight:400}.hljs-class .hljs-title,.hljs-type{color:#458;font-weight:500}.hljs-attribute,.hljs-name,.hljs-tag{color:navy;font-weight:400}.hljs-link,.hljs-regexp{color:#009926}.hljs-bullet,.hljs-symbol{color:#990073}.hljs-built_in,.hljs-builtin-name{color:#0086b3}.hljs-meta{color:#999;font-weight:500}.hljs-deletion{background:#fdd}.hljs-addition{background:#dfd}.hljs-emphasis{font-style:italic}.hljs-strong{font-weight:500}div.homepage-section h3,div.homepage-section p{color:#fff;margin:0}div.homepage-section h3{padding-bottom:.2em}div.homepage-section a.homepage-link-primary h3{font-size:28px}div.homepage-section a.homepage-link-secondary p{font-size:16px}div.homepage-section a.homepage-link-secondary h3{font-size:20px}div.homepage-section a.homepage-link-secondary p{font-size:14px}div.homepage-section-container{display:-webkit-box;display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap}div.homepage-section a.homepage-link{display:block;padding:16px;margin:10px;border-radius:10px}.homepage-page{margin-top:2.5em}div.homepage-section a.homepage-link:hover{text-decoration:none}div.homepage-section a.homepage-link-primary{background:transparent radial-gradient(ellipse at 50% 50%,#294172 15%,#233862 70%) repeat scroll 0 0;-webkit-box-flex:1;-ms-flex:1 1 300px;flex:1 1 300px}div.homepage-section a.homepage-link-primary:hover{background-color:#ddd}div.homepage-section a.homepage-link-secondary{background-color:#3c6eb4;font-size:.8em;-webkit-box-flex:1;-ms-flex:1 1 200px;flex:1 1 200px}div.home-page div.container-header{padding:20px 10px 0}div.home-page div.container-header h2{margin:0;border:none;padding:0}.homepage-page div h2{margin:1em -1rem .3em;padding:.8rem 1.5rem!important;font-size:34px!important;color:#294172!important;background-image:-webkit-gradient(linear,left top,left bottom,from(#eee),to(#ddd));background-image:linear-gradient(180deg,#eee,#ddd);border-bottom:none!important}div.home-page div.container-contributors,div.home-page div.container-project,div.home-page div.container-releases{margin-bottom:30px;display:-webkit-box;display:-ms-flexbox;display:flex;-ms-flex-wrap:wrap;flex-wrap:wrap}div.home-page div.container-contributors a,div.home-page div.container-project a,div.home-page div.container-releases a{display:block;background-color:#233862;color:#fff;text-decoration:none;padding:10px;margin:10px}div.home-page div.container-contributors h3,div.home-page div.container-project h3,div.home-page div.container-releases h3{color:#fff}div.home-page div.container-releases a{background-color:#173e77}div.home-page div.container-project a{background-color:#680959}div.home-page div.container-contributors a{background-color:#984f15}div.home-page .flex-container a.container-big{-webkit-box-flex:500px;-ms-flex:500px;flex:500px}div.home-page .flex-container a.container-small{-webkit-box-flex:200px;-ms-flex:200px;flex:200px}div.home-page .flex-container a.container-third{-webkit-box-flex:1;-ms-flex:1 1 500px;flex:1 1 500px}.flex-container p,div.home-page .flex-container h3{margin:10px}#contributing{text-align:center;background-color:#e6e6e6;margin:40px;padding:10px}#contributing h3{font-size:1em;margin:0}#contributing p.contributors{margin:0} \ No newline at end of file diff --git a/docs/public/_/font/roboto-latin-400.woff b/docs/public/_/font/roboto-latin-400.woff new file mode 100644 index 0000000..92dfacc Binary files /dev/null and b/docs/public/_/font/roboto-latin-400.woff differ diff --git a/docs/public/_/font/roboto-latin-400.woff2 b/docs/public/_/font/roboto-latin-400.woff2 new file mode 100644 index 0000000..7e854e6 Binary files /dev/null and b/docs/public/_/font/roboto-latin-400.woff2 differ diff --git a/docs/public/_/font/roboto-latin-400italic.woff b/docs/public/_/font/roboto-latin-400italic.woff new file mode 100644 index 0000000..27c34da Binary files /dev/null and b/docs/public/_/font/roboto-latin-400italic.woff differ diff --git a/docs/public/_/font/roboto-latin-400italic.woff2 b/docs/public/_/font/roboto-latin-400italic.woff2 new file mode 100644 index 0000000..3791c88 Binary files /dev/null and b/docs/public/_/font/roboto-latin-400italic.woff2 differ diff --git a/docs/public/_/font/roboto-latin-500.woff b/docs/public/_/font/roboto-latin-500.woff new file mode 100644 index 0000000..2633e15 Binary files /dev/null and b/docs/public/_/font/roboto-latin-500.woff differ diff --git a/docs/public/_/font/roboto-latin-500.woff2 b/docs/public/_/font/roboto-latin-500.woff2 new file mode 100644 index 0000000..8dceabc Binary files /dev/null and b/docs/public/_/font/roboto-latin-500.woff2 differ diff --git a/docs/public/_/font/roboto-latin-500italic.woff b/docs/public/_/font/roboto-latin-500italic.woff new file mode 100644 index 0000000..d4d8b15 Binary files /dev/null and b/docs/public/_/font/roboto-latin-500italic.woff differ diff --git a/docs/public/_/font/roboto-latin-500italic.woff2 b/docs/public/_/font/roboto-latin-500italic.woff2 new file mode 100644 index 0000000..1b95899 Binary files /dev/null and b/docs/public/_/font/roboto-latin-500italic.woff2 differ diff --git a/docs/public/_/font/roboto-mono-latin-400.woff b/docs/public/_/font/roboto-mono-latin-400.woff new file mode 100644 index 0000000..0ea5db8 Binary files /dev/null and b/docs/public/_/font/roboto-mono-latin-400.woff differ diff --git a/docs/public/_/font/roboto-mono-latin-400.woff2 b/docs/public/_/font/roboto-mono-latin-400.woff2 new file mode 100644 index 0000000..6163de7 Binary files /dev/null and b/docs/public/_/font/roboto-mono-latin-400.woff2 differ diff --git a/docs/public/_/font/roboto-mono-latin-500.woff b/docs/public/_/font/roboto-mono-latin-500.woff new file mode 100644 index 0000000..b12f6a1 Binary files /dev/null and b/docs/public/_/font/roboto-mono-latin-500.woff differ diff --git a/docs/public/_/font/roboto-mono-latin-500.woff2 b/docs/public/_/font/roboto-mono-latin-500.woff2 new file mode 100644 index 0000000..125f098 Binary files /dev/null and b/docs/public/_/font/roboto-mono-latin-500.woff2 differ diff --git a/docs/public/_/img/back.svg b/docs/public/_/img/back.svg new file mode 100644 index 0000000..201c83f --- /dev/null +++ b/docs/public/_/img/back.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/public/_/img/caret.svg b/docs/public/_/img/caret.svg new file mode 100644 index 0000000..99857c1 --- /dev/null +++ b/docs/public/_/img/caret.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/public/_/img/chevron.svg b/docs/public/_/img/chevron.svg new file mode 100644 index 0000000..c397621 --- /dev/null +++ b/docs/public/_/img/chevron.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/public/_/img/close.svg b/docs/public/_/img/close.svg new file mode 100644 index 0000000..b4a8088 --- /dev/null +++ b/docs/public/_/img/close.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/public/_/img/docs_logo.png b/docs/public/_/img/docs_logo.png new file mode 100644 index 0000000..271f4cc Binary files /dev/null and b/docs/public/_/img/docs_logo.png differ diff --git a/docs/public/_/img/home-o.svg b/docs/public/_/img/home-o.svg new file mode 100644 index 0000000..95d193b --- /dev/null +++ b/docs/public/_/img/home-o.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/public/_/img/home.svg b/docs/public/_/img/home.svg new file mode 100644 index 0000000..4e96b35 --- /dev/null +++ b/docs/public/_/img/home.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/public/_/img/menu.svg b/docs/public/_/img/menu.svg new file mode 100644 index 0000000..8b43b2e --- /dev/null +++ b/docs/public/_/img/menu.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/docs/public/_/js/site.js b/docs/public/_/js/site.js new file mode 100644 index 0000000..124268d --- /dev/null +++ b/docs/public/_/js/site.js @@ -0,0 +1,4 @@ +!function(){"use strict";function e(n){3!==n.which&&2!==n.button&&(document.documentElement.classList.remove("is-clipped--nav"),s.classList.remove("is-active"),i.classList.remove("is-active"),window.removeEventListener("click",e),t(n))}function t(e){e.stopPropagation()}function n(){window.sessionStorage.setItem("nav-state",JSON.stringify(c))}function a(e,t){return[].slice.call((t||document).querySelectorAll(e))}var i=document.querySelector(".navigation-container"),s=document.querySelector(".navigation-toggle");s.addEventListener("click",function(n){if(s.classList.contains("is-active"))return e(n);document.documentElement.classList.add("is-clipped--nav"),s.classList.add("is-active"),i.classList.add("is-active"),window.addEventListener("click",e),t(n)}),i.addEventListener("click",t);var o=i.querySelector("[data-panel=menu]");if(o){var c=function(){var e=window.sessionStorage.getItem("nav-state");return e&&"1"===(e=JSON.parse(e)).__version__?e:{__version__:"1"}}(),r=function(e,t,n){var a=n+"@"+t;return e[a]||(e[a]={})}(c,i.dataset.component,i.dataset.version);i.querySelector(".context").addEventListener("click",function(){var e=i.querySelector(".is-active[data-panel]"),t="menu"===e.dataset.panel?"explore":"menu";e.classList.toggle("is-active"),i.querySelector("[data-panel="+t+"]").classList.toggle("is-active")}),a(".nav-toggle",o).forEach(function(e){var t=e.parentElement;e.addEventListener("click",function(){t.classList.toggle("is-active"),r.expandedItems=a(".is-active",o).map(function(e){return e.dataset.id}),n()})}),a(".nav-item",o).forEach(function(e,t){e.setAttribute("data-id","menu-"+e.dataset.depth+"-"+t)});var d=r.expandedItems||(r.expandedItems=[]);d.length&&a(d.map(function(e){return'.nav-item[data-id="'+e+'"]'}).join(","),o).forEach(function(e){e.classList.add("is-active")});var l=o.querySelector(".is-current-page");l&&function(e){for(var t,n=[e.dataset.id],a=e.parentNode;!(t=a.classList).contains("nav-menu");)"LI"===a.tagName&&t.contains("nav-item")&&(t.add("is-active","is-current-path"),n.push(a.dataset.id)),a=a.parentNode;return e.classList.add("is-active"),n}(l).forEach(function(e){d.indexOf(e)<0&&d.push(e)}),n(),function(e,t,n){if(!n)return t.scrollTop=e;var a=n.offsetTop-e<0,i=n.offsetTop-e+n.offsetHeight>t.offsetHeight;t.scrollTop=a?n.offsetTop-10:i?n.offsetTop-(t.offsetHeight-n.offsetHeight)+10:e}(r.scroll||0,o,l&&l.querySelector(".nav-link")),o.addEventListener("scroll",function(){r.scroll=Math.round(o.scrollTop),n()})}}(); +!function(){"use strict";function e(t,o){return n.contains(t)?e(t.offsetParent,t.offsetTop+o):o}function t(t){t&&(window.location.hash="#"+this.id,t.preventDefault()),window.scrollTo(0,e(this,0)-o.getBoundingClientRect().bottom)}var n=document.querySelector("article.doc"),o=document.querySelector(".toolbar");window.addEventListener("load",function e(n){var o,i;(o=window.location.hash)&&(i=document.getElementById(o.slice(1)))&&t.bind(i)(),window.removeEventListener("load",e)}),Array.prototype.slice.call(document.querySelectorAll('a[href^="#"]')).forEach(function(e){var n,o;(n=e.hash.slice(1))&&(o=document.getElementById(n))&&e.addEventListener("click",t.bind(o))})}(); +!function(){"use strict";var e=document.querySelector(".page-versions .versions-menu-toggle");if(e){var t=document.querySelector(".page-versions");e.addEventListener("click",function(e){t.classList.toggle("is-active"),e.stopPropagation()}),window.addEventListener("click",function(){t.classList.remove("is-active")})}}(); +document.addEventListener("DOMContentLoaded",function(){var t=Array.prototype.slice.call(document.querySelectorAll(".navbar-burger"),0);0!==t.length&&t.forEach(function(t){t.addEventListener("click",function(e){e.stopPropagation(),t.classList.toggle("is-active"),document.getElementById(t.dataset.target).classList.toggle("is-active"),document.documentElement.classList.toggle("is-clipped--navbar")})})}); \ No newline at end of file diff --git a/docs/public/_/js/vendor/docsearch.min.js b/docs/public/_/js/vendor/docsearch.min.js new file mode 100644 index 0000000..f807026 --- /dev/null +++ b/docs/public/_/js/vendor/docsearch.min.js @@ -0,0 +1 @@ +!function t(e,n,r){function i(o,a){if(!n[o]){if(!e[o]){var u="function"==typeof require&&require;if(!a&&u)return u(o,!0);if(s)return s(o,!0);var c=new Error("Cannot find module '"+o+"'");throw c.code="MODULE_NOT_FOUND",c}var l=n[o]={exports:{}};e[o][0].call(l.exports,function(t){var n=e[o][1][t];return i(n||t)},l,l.exports,t,e,n,r)}return n[o].exports}for(var s="function"==typeof require&&require,o=0;o=31},n.storage="undefined"!=typeof chrome&&void 0!==chrome.storage?chrome.storage.local:function(){try{return window.localStorage}catch(t){}}(),n.colors=["lightseagreen","forestgreen","goldenrod","dodgerblue","darkorchid","crimson"],n.formatters.j=function(t){return JSON.stringify(t)},n.enable(r())},{"./debug":2}],2:[function(t,e,n){(n=e.exports=function(t){function e(){}function s(){var t=s,e=+new Date,o=e-(r||e);t.diff=o,t.prev=r,t.curr=e,r=e,null==t.useColors&&(t.useColors=n.useColors()),null==t.color&&t.useColors&&(t.color=n.colors[i++%n.colors.length]);var a=Array.prototype.slice.call(arguments);a[0]=n.coerce(a[0]),"string"!=typeof a[0]&&(a=["%o"].concat(a));var u=0;a[0]=a[0].replace(/%([a-z%])/g,function(e,r){if("%%"===e)return e;u++;var i=n.formatters[r];if("function"==typeof i){var s=a[u];e=i.call(t,s),a.splice(u,1),u--}return e}),"function"==typeof n.formatArgs&&(a=n.formatArgs.apply(t,a)),(s.log||n.log||console.log.bind(console)).apply(t,a)}e.enabled=!1,s.enabled=!0;var o=n.enabled(t)?s:e;return o.namespace=t,o}).coerce=function(t){return t instanceof Error?t.stack||t.message:t},n.disable=function(){n.enable("")},n.enable=function(t){n.save(t);for(var e=(t||"").split(/[\s,]+/),r=e.length,i=0;i1e4)){var e=/^((?:\d+)?\.?\d+) *(milliseconds?|msecs?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h|days?|d|years?|yrs?|y)?$/i.exec(t);if(e){var n=parseFloat(e[1]);switch((e[2]||"ms").toLowerCase()){case"years":case"year":case"yrs":case"yr":case"y":return n*u;case"days":case"day":case"d":return n*a;case"hours":case"hour":case"hrs":case"hr":case"h":return n*o;case"minutes":case"minute":case"mins":case"min":case"m":return n*s;case"seconds":case"second":case"secs":case"sec":case"s":return n*i;case"milliseconds":case"millisecond":case"msecs":case"msec":case"ms":return n}}}}(t):e.long?function(t){return r(t,a,"day")||r(t,o,"hour")||r(t,s,"minute")||r(t,i,"second")||t+" ms"}(t):function(t){return t>=a?Math.round(t/a)+"d":t>=o?Math.round(t/o)+"h":t>=s?Math.round(t/s)+"m":t>=i?Math.round(t/i)+"s":t+"ms"}(t)}},{}],4:[function(t,e,n){!function(t,r){"object"==typeof n&&"object"==typeof e?e.exports=r():"function"==typeof define&&define.amd?define([],r):"object"==typeof n?n.docsearch=r():t.docsearch=r()}("undefined"!=typeof self?self:this,function(){return function(t){function e(r){if(n[r])return n[r].exports;var i=n[r]={i:r,l:!1,exports:{}};return t[r].call(i.exports,i,i.exports,e),i.l=!0,i.exports}var n={};return e.m=t,e.c=n,e.d=function(t,n,r){e.o(t,n)||Object.defineProperty(t,n,{configurable:!1,enumerable:!0,get:r})},e.n=function(t){var n=t&&t.__esModule?function(){return t.default}:function(){return t};return e.d(n,"a",n),n},e.o=function(t,e){return Object.prototype.hasOwnProperty.call(t,e)},e.p="",e(e.s=21)}([function(t,e,n){"use strict";function r(t){return t.replace(/[\-\[\]\/\{\}\(\)\*\+\?\.\\\^\$\|]/g,"\\$&")}var i=n(1);t.exports={isArray:null,isFunction:null,isObject:null,bind:null,each:null,map:null,mixin:null,isMsie:function(){return!!/(msie|trident)/i.test(navigator.userAgent)&&navigator.userAgent.match(/(msie |rv:)(\d+(.\d+)?)/i)[2]},escapeRegExChars:function(t){return t.replace(/[\-\[\]\/\{\}\(\)\*\+\?\.\\\^\$\|]/g,"\\$&")},isNumber:function(t){return"number"==typeof t},toStr:function(t){return void 0===t||null===t?"":t+""},cloneDeep:function(t){var e=this.mixin({},t),n=this;return this.each(e,function(t,r){t&&(n.isArray(t)?e[r]=[].concat(t):n.isObject(t)&&(e[r]=n.cloneDeep(t)))}),e},error:function(t){throw new Error(t)},every:function(t,e){var n=!0;return t?(this.each(t,function(r,i){if(!(n=e.call(null,r,i,t)))return!1}),!!n):n},any:function(t,e){var n=!1;return t?(this.each(t,function(r,i){if(e.call(null,r,i,t))return n=!0,!1}),n):n},getUniqueId:function(){var t=0;return function(){return t++}}(),templatify:function(t){if(this.isFunction(t))return t;var e=i.element(t);return"SCRIPT"===e.prop("tagName")?function(){return e.text()}:function(){return String(t)}},defer:function(t){setTimeout(t,0)},noop:function(){},formatPrefix:function(t,e){return e?"":t+"-"},className:function(t,e,n){return(n?"":".")+t+e},escapeHighlightedString:function(t,e,n){e=e||"";var i=document.createElement("div");i.appendChild(document.createTextNode(e)),n=n||"";var s=document.createElement("div");s.appendChild(document.createTextNode(n));var o=document.createElement("div");return o.appendChild(document.createTextNode(t)),o.innerHTML.replace(RegExp(r(i.innerHTML),"g"),e).replace(RegExp(r(s.innerHTML),"g"),n)}}},function(t,e,n){"use strict";t.exports={element:null}},function(t,e){var n=Object.prototype.hasOwnProperty,r=Object.prototype.toString;t.exports=function(t,e,i){if("[object Function]"!==r.call(e))throw new TypeError("iterator must be a function");var s=t.length;if(s===+s)for(var o=0;o was loaded but did not call our provided callback"),JSONPScriptError:i("JSONPScriptError"," + + +Redirect Notice +

Redirect Notice

+

The page you requested has been relocated to websites/.

diff --git a/docs/public/websites/fedora-release/index.html b/docs/public/websites/fedora-release/index.html new file mode 100644 index 0000000..97f0cb6 --- /dev/null +++ b/docs/public/websites/fedora-release/index.html @@ -0,0 +1,309 @@ + + + + + + Fedora Release :: Fedora Websites + + + + + +
+
+ +
+
+ +
+

Fedora Release

+
+

Introduction

+
+
+ + + + + +
+ + +
+

This assume you have a working setup already. See the other documents (e.g. the +one using Docker to get a development environment working) to get set up. Also, +if using a container-based environment, ensure that the image you’re using +reflects the latest Dockerfile in the root of the repository.

+
+
+
+
+

This document guides you through updating the websites for a release (beta or +GA) of Fedora.

+
+
+

Most of the work comes down to editing one file, +sites/getfedora.org/release.yaml. What follows are the important points to +note.

+
+
+

The release.yaml file is broken into several main sections, and the relevant +ones are ga, beta, fmw, and gpg_keys.

+
+
+ + + + + +
+ + +
+

Pushing to the staging branch will update https://stg.getfedora.org/, which +pushing to the master branch will update https://getfedora.org/.

+
+
+
+
+

Beta Releases

+
+

If you are updating for a beta release, then you are free to leave the ga +section alone.

+
+
+

In the beta section, you’ll want show to be true. This toggles whether we +show the beta download links at all. It also changes the banner at the top of +the website to announce the beta instead of the previous GA release. The +announcement_release_number dictates which version number is shown in that +announcement, so you’ll want to bump it to the beta version being released.

+
+
+

Next you’ll want to edit the editions section, still under the beta parent +section. Bump the release_number and set the rc_version to the RC that was +called gold/ready for release. Find this information out from releng, if +necessary.

+
+
+
+
+
+

GA Releases

+
+
+

If you are updating for a ga release, then in the beta section, set show +to false, so that the beta downloads don’t show, and the announcement at the +top of the landing site reflects the new GA. Check with someone (usually Paul +Frields (stickster on IRC) to find the URL of the Fedora Magazine announcement +for the release, and set announcement_url to that, in the ga section.

+
+
+

Next, bump the release_number and rc_version of each edition under +editions, using the rc_version that was declared gold/ready for +release. Find this information out from releng, if necessary.

+
+
+
+
+

releases.json file

+
+
+

The next step is to produce the releases.json static file used by Fedora Media +Writer to produce its list of possible downloads. In the fmw section of +release.yaml, update the releases_json list to include the current non-EOL +versions of Fedora, including any current betas. If a version is in beta, set +the its milestone to beta. Otherwise set it to final or leave out the +field altogether.

+
+
+

For example:

+
+
+
+
fmw:
+  ...
+  releases_json:
+    - version: 31
+      milestone: beta
+    - version: 30
+    - version: 29
+
+
+
+

Once this is done, you’ll need to actually generate the releases.json file.

+
+
+

If using a containerized environment, you can do this from the root of the +repository (replacing sudo docker with podman if you use Podman):

+
+
+
+
sudo docker run -it --rm -v "$(pwd):/opt/:z" fedora-websites python ./scripts/releases-json.py > sites/getfedora.org/static/releases.json
+
+
+
+

Otherwise, if you’re not using a containerized environment, you can run the +script yourself after installing the python-fedfind package. From the root of +the repository:

+
+
+
+
python3 sites/getfedora.org/scripts/releases-json.py > sites/getfedora.org/static/releases.json
+
+
+
+

Check that releases.json looks sane (it should look like a blob of JSON), then +move on.

+
+
+
+
+

Checksum Files

+
+
+

You’ll need to import the checksum files into +sites/getfedora.org/static/checksums/. To find out which checksums you need to +import, you can simply do a build of getfedora.org, and it will error out and +tell you what is missing. This is by design to ensure we don’t miss a checksum +file.

+
+
+
+
+

GPG Keys

+
+
+

Lastly, you’ll want to add the latest GPG key information to gpg_keys in +release.yaml. Follow the pattern that is already there, and move any now-EOL +releases into the obsolete subsection.

+
+
+

Import any new GPG keys into sites/getfedora.org/static/keys/, naming the file +[short key id].txt e.g. 57BBCCBA.txt.

+
+
+
+
+

Conclusion

+
+
+

That should be all. The old sites (namely spins, labs, alt, arm) which haven’t +been ported to the new system need to be updated separately and are beyond the +scope of this document.

+
+
+

Commit your changes, and they should auto-deploy within two hours at most.

+
+
+
+
+
+

These nice people helped write this page:

+

Rick Elrod

+

Want to help? Learn how to contribute to Fedora Docs.

+
+
+
+

All Fedora Documentation content available under CC-BY-SA 3.0 or, when specifically noted, under another accepted free and open content license.

+

Last build:

+
+ + + + + diff --git a/docs/public/websites/index.html b/docs/public/websites/index.html new file mode 100644 index 0000000..ea82214 --- /dev/null +++ b/docs/public/websites/index.html @@ -0,0 +1,157 @@ + + + + + + Fedora Websites :: Fedora Websites + + + + + +
+
+ +
+
+ +
+

Fedora Websites

+
+

The Fedora Websites project owns and maintains the Project’s online presence. +Among other things, the team:

+
+
+
    +
  • +

    Works closely with the +Fedora Design team to build +our websites in a way that is visually pleasing, easy to use, accessible to +everybody, and provides a good experience for newcomers and existing users +and contributors alike.

    +
    • +
  • +

    Works closely with the +Fedora Translations team to +ensure that websites are able to be translated into different languages.

    +
    • +
  • +

    Maintains the content of the websites, updating it as necessary for releases, +new editions, new spins, and so on.

    +
    • +
  • +

    Typically has one member (either in Design or Websites) who sits on the +Fedora Mindshare committee.

    +
    • +
+
+
+
+

These nice people helped write this page:

+

Rick Elrod, Ryan Lerch

+

Want to help? Learn how to contribute to Fedora Docs.

+
+
+
+

All Fedora Documentation content available under CC-BY-SA 3.0 or, when specifically noted, under another accepted free and open content license.

+

Last build:

+
+ + + + + diff --git a/docs/public/websites/newcontent-edition/index.html b/docs/public/websites/newcontent-edition/index.html new file mode 100644 index 0000000..e811359 --- /dev/null +++ b/docs/public/websites/newcontent-edition/index.html @@ -0,0 +1,263 @@ + + + + + + New Edition :: Fedora Websites + + + + + +
+
+ +
+
+ +
+

New Edition

+
+

Introduction

+
+
+

Fedora editions are "versions" of Fedora that users can install. These include +"official" editions (Workstation and Server at time of writing), but the +ultimate goal in Websites is to also make Spins and Labs editions be considered +"editions" in some form as far as websites are concerned. That is to say, we’d +like to ultimately have Spins and Labs have a section on the main getfedora.org +site, rendering https://spins.fedorparoject.org/ and +https://labs.fedoraproject.org/ useless and able to be gotten rid of. +Doing this effectively will take some time.

+
+
+

Also note that most of the content in this document applies to adding pages in +general, with the notable exception of the release.yaml edits. Adding a page +to getfedora.org should follow largely the same process, though.

+
+
+ + + + + +
+ + +
+

All new editions should be added to getfedora.org, to aid in our goal of getting +rid of all of the *.fedoraproject.org edition-specific subdomain sites. This +generates a more consistent and less confusing user experience and makes +maintenance of the websites easier going forward. Everything in this document +assumes that you are working with the getfedora.org codebase, and NOT creating a +new site from scratch.

+
+
+
+
+

Now then, all work in this document takes place in the repository in which +getfedora.org lives, and particularly +in the sites/getfedora.org/ directory.

+
+
+
+
+

Edition-specific Release Variables

+
+
+

The first step is to edit release.yaml, and add the relevant sections under +ga and beta for your new edition. Use workstation and server as +templates. You might not need all variables that these existing sections have, +or you might need to add new ones, depending on your templates, but these blocks +should get you started.

+
+
+
+
+

Exporting the Edition Routes

+
+
+

Now, open main.py and go to near the bottom, where you’ll note a number of +export_route(…​) calls. This method is a custom method defined earlier in the +file, which does a little bit of work for us: The first argument is an internal +identifier name, so that we can reference the page using url_for safely (if +the URL changes, so will the URLs that get generated by url_for). The second +argument is a path to the directory that contains the templates you’ll make, but +with a preceding and trailing /. Follow the example of the other, currently +existing pages and add the appropriate export_route calls at the end.

+
+
+
+
+

Hacking the Templates

+
+
+

The templates themselves live in the sites directory (under +sites/getfedora.org/ still). There are already templates started (but not +currently exported in main.py) for silverblue, coreos, and iot, at time +of writing.

+
+
+ + + + + +
+ + +
+

Every string you add must be enclosed in {% trans %} …​ {% endtrans %} +blocks so that it can be translated. If the string spans multiple lines (we tend +to break at 80 characters but are fairly lenient about this), then the opening +block should instead be {% trans trimmed %} (the closing block is still just +{% endtrans %}).

+
+
+
+
+

You can copy the templates from the existing editions, if you need inspiration +or help.

+
+
+
+
+

Letting the Translators Do Their Thing

+
+
+

Once the above is done, the next step is get all the strings in the hands of the +Fedora Translations team. If you have an account on Fedora’s Zanata instance, +and are in the appropriate websites group on Zanata, and have a valid +~/.config/zanata.ini file, you can do this step yourself. Otherwise you’ll +either need to be added to the appropriate team or have someone do this for you:

+
+
+

Run ./scripts/translations-source.sh. At the end of its output, it will give +you the Zanata command to push the strings up: zanata push getfedora.org.pot

+
+
+
+
+

Concluding

+
+
+

Largely, that is it. You’ve added variables that are easy to update each release +(in release.yaml), you’ve exported the pages, written your templates in a +translatable way, and pushed those strings to the Translations team. Now you can +sit back and relax while the translators do their thing. Their translations will +go live immediately (well, within an hour) and automatically.

+
+
+
+
+
+

These nice people helped write this page:

+

Rick Elrod

+

Want to help? Learn how to contribute to Fedora Docs.

+
+
+
+

All Fedora Documentation content available under CC-BY-SA 3.0 or, when specifically noted, under another accepted free and open content license.

+

Last build:

+
+ + + + + diff --git a/docs/public/websites/newcontent-site/index.html b/docs/public/websites/newcontent-site/index.html new file mode 100644 index 0000000..b1879d9 --- /dev/null +++ b/docs/public/websites/newcontent-site/index.html @@ -0,0 +1,147 @@ + + + + + + Creating A New Site :: Fedora Websites + + + + + +
+
+ +
+
+ +
+

Creating A New Site

+
+

In rare cases, you might need to create an entirely new site, rather than an +edition or page on getfedora.org.

+
+
+

In a future world, this document will help you do so.

+
+
+

For this to happen effectively, we’ll need to abstract some things out from the +current getfedora.org work.

+
+
+

But familiarizing yourself with Flask +and Frozen-Flask is a good starting +point, as we plan for all of our websites to build using this toolset.

+
+
+
+

These nice people helped write this page:

+

Rick Elrod

+

Want to help? Learn how to contribute to Fedora Docs.

+
+
+
+

All Fedora Documentation content available under CC-BY-SA 3.0 or, when specifically noted, under another accepted free and open content license.

+

Last build:

+
+ + + + + diff --git a/docs/public/websites/newcontent/index.html b/docs/public/websites/newcontent/index.html new file mode 100644 index 0000000..ae335de --- /dev/null +++ b/docs/public/websites/newcontent/index.html @@ -0,0 +1,164 @@ + + + + + + Creating New Content :: Fedora Websites + + + + + +
+
+ +
+
+ +
+

Creating New Content

+
+
+
+

Content can be broken into several different components, although some of the +process is the same for all cases.

+
+
+

All new sites are being built with the Python Flask +framework and the Frozen-Flask library +for generating static pages.

+
+
+
+
+

New Editions

+
+
+

New editions of Fedora should be added to the getfedora.org website. We are +trying to get away from having a bunch of *.fedoraproject.org sites for each +of the various editions (currently we have https://coreos.fedoraproject.org, +https://iot.fedoraproject.org, etc.).

+
+
+
+
+

New Websites

+
+
+

There are cases, however, where the content being added is not a new edition, +and is deserving of having its own distinct website, separate from +getfedora.org. These cases should probably be somewhat rare.

+
+
+
+
+
+

These nice people helped write this page:

+

Rick Elrod

+

Want to help? Learn how to contribute to Fedora Docs.

+
+
+
+

All Fedora Documentation content available under CC-BY-SA 3.0 or, when specifically noted, under another accepted free and open content license.

+

Last build:

+
+ + + + + diff --git a/docs/public/websites/setup-docker/index.html b/docs/public/websites/setup-docker/index.html new file mode 100644 index 0000000..26ca53b --- /dev/null +++ b/docs/public/websites/setup-docker/index.html @@ -0,0 +1,235 @@ + + + + + + Getting Set Up (using Docker) :: Fedora Websites + + + + + +
+
+ +
+
+ +
+

Getting Set Up (using Docker)

+
+

Preliminary Notes

+
+
+

It is now easier to get started on developing the Fedora Websites with the use +of Docker (or Podman).

+
+
+

We ship a Dockerfile which will install dependencies into an image +for you, so all you are left to do is mount the site as a volume, pull +translations, and start the development server.

+
+
+ + + + + +
+ + +
+

The documentation here refers to docker, but our fairly simple use +of it means that things are likely to work with podman with little +modification.

+
+
+
+
+
+
+

Building the container image

+
+
+

First clone the repository:

+
+
+
+
git clone https://pagure.io/fedora-web/websites.git
+
+
+
+

(You may instead clone your fork of it, or add your fork as a second +remote later on.)

+
+
+

Now ensure Docker is running and run:

+
+
+
+
sudo docker build -t fedora-websites .
+
+
+
+

This will generate a container image for you to use.

+
+
+
+
+

Pulling translations

+
+
+

We have a script for pulling translations. Let’s call it from within +the container:

+
+
+
+
sudo docker run -it --rm -v "$(pwd):/opt/:z" fedora-websites ./scripts/pull-translations.sh
+
+
+
+

Notice here that we are mounting a volume (-v) in Docker which +points to our check-out of the repository. We’re referring to the +fedora-websites image created above, and calling the +./scripts/pull-translations.sh script from within it.

+
+
+
+
+

Running the development server

+
+
+

Now we are ready to run the development server:

+
+
+
+
sudo docker run -it --rm -v "$(pwd):/opt/:z" -p 5000:5000 fedora-websites flask run --reload --host 0.0.0.0
+
+
+
+

Note that we need -p 5000:5000 so that we can access the development +server from our actual host. Also notice that we need to tell Flask to +listen on 0.0.0.0 as by default it listens on 127.0.0.1 which +won’t be accessible outside of the container.

+
+
+

You may now go to http://localhost:5000/ in your browser of choice.

+
+
+

Now you are ready to go and any changes you make in the repository +should be reflected immediately upon refreshing the page in your +browser.

+
+
+
+
+
+

These nice people helped write this page:

+

Rick Elrod

+

Want to help? Learn how to contribute to Fedora Docs.

+
+
+
+

All Fedora Documentation content available under CC-BY-SA 3.0 or, when specifically noted, under another accepted free and open content license.

+

Last build:

+
+ + + + + diff --git a/docs/public/websites/setup/index.html b/docs/public/websites/setup/index.html new file mode 100644 index 0000000..b867dc3 --- /dev/null +++ b/docs/public/websites/setup/index.html @@ -0,0 +1,284 @@ + + + + + + Getting Set Up :: Fedora Websites + + + + + +
+
+ +
+
+ +
+

Getting Set Up

+
+
+
+ + + + + +
+ + +
+

We now have documentation on using the Dockerfile which ships in the Fedora +websites repository, and suggest trying that method before using the method +outlined on this page. See this tutorial.

+
+
+
+
+
+
+

Preliminary Notes

+
+
+

There are some open tickets (31, +11) about getting the websites +repository building on Fedora with Python 3.

+
+
+

However, it should be able to be built on Fedora 30, using Python 2 packages, +for now.

+
+
+

Fedora 29 Alternative

+
+

Note, the dependencies below may not currently resolve due to package renaming +in Fedora 30. If the dependencies do not resolve in Fedora 30, running Flask +from a Fedora 29 container is an alternative. An example to run the Fedora 29 +container using podman is as follows:

+
+
+
+
# Expose the default port for Flask, 5000.
+podman run --expose 5000 --net=host --privileged -v /path/to/websites/repo:/path/to/websites/repo -ti registry.fedoraproject.org/fedora:29
+
+
+
+
+
+
+

Dependencies

+
+
+

That said, assuming Fedora 30, install the dependencies as follows +[1]:

+
+
+
+
dnf install \
+        git \
+        python-flask \
+        python-frozen-flask \
+        python-flask-assets \
+        python-rjsmin \
+        python-cssmin \
+        python-flask-babel \
+        python-flask-htmlmin \
+        python-cssutils \
+        rubygem-sass \
+        babel \
+        python3-jinja2 \
+        python-pyyaml \
+        python-dateutil \
+        python-dogpile-cache \
+        python-requests \
+        python-zanata-client
+
+
+
+
+
+

Pull Strings

+
+
+

Now we need to pull the current translations. After installing the dependencies +above, you can cd into sites/getfedora.org/ and run: +./scripts/pull-translations.sh.

+
+
+

Once the dependencies are installed and translations are pulled, you can do one +of two things:

+
+
+
+
+

Use the Development Server

+
+
+

One option is to use the Flask built-in development server. This is handy +because it prevents you from needing to build the websites every time you change +something. However, it bypasses the Frozen-Flask system which creates are static +sites, entirely, so it’s not entirely an accurate representation of what goes +live.

+
+
+

To use the development server:

+
+
+
+
export FLASK_APP=main.py
+flask run --reload
+
+
+
+

Now you many visit http://localhost:5000/ to get to the site.

+
+
+
+
+

Use Apache

+
+
+

Alternatively, you may simply run python main.py. You’ll get a statically +built site in the ./build/ directory. However, the HTML files are all +language-code-suffixed as Apache/httpd MultiViews system expects +(e.g. index.html.en). As a result you cannot just run a simple HTTP server +(like python -m SimpleHTTPServer) in the ./build/ directory, unfortunately.

+
+
+

You can, however, set up an Apache on your system, and point it to the +./build/ directory.

+
+
+ + + + + +
+ + +
+

(We should probably add an example Apache config here at some point).

+
+
+
+
+
+
+
+
+1. This list comes directly from the Fedora Infrastructure OpenShift build for Websites found here. +
+
+
+
+

These nice people helped write this page:

+

Rick Elrod

+

Want to help? Learn how to contribute to Fedora Docs.

+
+
+
+

All Fedora Documentation content available under CC-BY-SA 3.0 or, when specifically noted, under another accepted free and open content license.

+

Last build:

+
+ + + + + diff --git a/docs/public/websites/team/index.html b/docs/public/websites/team/index.html new file mode 100644 index 0000000..1d8733d --- /dev/null +++ b/docs/public/websites/team/index.html @@ -0,0 +1,138 @@ + + + + + + Fedora Websites & Apps Team Documentation :: Fedora Websites + + + + + +
+
+ +
+
+ +
+

Fedora Websites & Apps Team Documentation

+
+

This section of documentation is meta documentation for the Websites & Apps Team best practices. +These documents are less about our projects, and more about how we work together and collaborate as a team. +Use the sidebar navigation to browse to other pages about the team.

+
+
+

include::../nav.adoc

+
+
+
+

These nice people helped write this page:

+

Fedora Websites &amp; Apps Community

+

Want to help? Learn how to contribute to Fedora Docs.

+
+
+
+

All Fedora Documentation content available under CC-BY-SA 3.0 or, when specifically noted, under another accepted free and open content license.

+

Last build:

+
+ + + + + diff --git a/docs/public/websites/team/meetings/index.html b/docs/public/websites/team/meetings/index.html new file mode 100644 index 0000000..9d49d66 --- /dev/null +++ b/docs/public/websites/team/meetings/index.html @@ -0,0 +1,184 @@ + + + + + + Guide to W&A meetings :: Fedora Websites + + + + + +
+
+ +
+
+ +
+

Guide to W&A meetings

+ +
+
+
+

This page is an overview of how the Fedora Websites & Apps Team runs meetings together as a community. +The article shares more about how we work and best practices that help keep our team meetings running smoothly. +If you think something is missing here, please open an issue or submit a patch to open a discussion with the team.

+
+
+
+
+

In-person meetings

+
+
+

In normal circumstances, occasional in-person meetings (or "hackfests") help us coordinate work and get to know each other as a team. +However, in light of current global circumstances with COVID-19, this travel is not yet an option. +When this option returns, this section of documentation can be revisited for new additions.

+
+
+
+
+

Synchronous virtual meetings

+
+
+

What are synchronous virtual meetings? +This is a fancy way of saying meetings where we are all sitting together at the same moment, across many time zones. +Any meeting participants can be an engaged part of the meeting.

+
+
+

Chat

+
+

We have not yet piloted chat-led meetings, given recent zodbot bridging challenges with IRC, Matrix, and Telegram.

+
+
+
+

Audio/Video

+
+

To be written.

+
+
+
+
+
+
+

These nice people helped write this page:

+

Justin W. Flory, Fedora Community

+

Want to help? Learn how to contribute to Fedora Docs.

+
+
+
+

All Fedora Documentation content available under CC-BY-SA 3.0 or, when specifically noted, under another accepted free and open content license.

+

Last build:

+
+ + + + + diff --git a/docs/public/websites/translation-flow/index.html b/docs/public/websites/translation-flow/index.html new file mode 100644 index 0000000..7e2af94 --- /dev/null +++ b/docs/public/websites/translation-flow/index.html @@ -0,0 +1,261 @@ + + + + + + Translation flow (for Fedora websites) :: Fedora Websites + + + + + +
+
+ +
+
+ +
+

Translation flow (for Fedora websites)

+
+

General

+
+
+

Fedora websites can be viewed in many languages. This page gives some details on how this happens.

+
+
+

Tagging text

+
+

System needs to be told what strings needs to be translated. +Generally every text inside web page should be surrounded with tags:

+
+
+
+
{% trans trimmed %}Translate this text.{% endtrans %}
+
+
+
+
+
+
+

Generating pot file

+
+
+

First we need to pull all translatable strings into a file called getfedora.org.pot

+
+
+

This file is generated by running:

+
+
+
+
podman run -it --rm -v "$(pwd):/opt/:z" fedora-websites ./scripts/translations-source.sh
+
+
+
+

This file needs to be sent to translations repository

+
+
+

If you don’t have access to the translations repository push it to fedora-websites and create a pull request and once approved it should be automatically sent to translations repository with 24 hours.

+
+
+
+
+

Weblate process (How strings get translated)

+
+
+

Once getfedora.org.pot file is in the translations repository it will be pulled by Weblate system and merged into translatable strings. It can then be translated by translators.

+
+
+
+
+

Manual testing

+
+
+ + + + + +
+ + +
+

Any translations made here will not get propagated to the weblate of final versions of the page.

+
+
+
+
+

You can test the changes manually by:

+
+
+

1) +Update strings to the language files

+
+
+
+
podman run -it --rm -v "$(pwd):/opt/:z" fedora-websites ./scripts/translations-update-local.sh
+
+
+
+

Now edit desired language file, for example

+
+
+
+
nano sites/getfedora.org/translations/fi/LC_MESSAGES/messages.po
+
+
+
+

Find the string you want to test, format inside file is:

+
+
+
+
`#: partials/templates/download_card.html:13`   Location(s) of string.
+`msgid "Download"`   Text in english.
+`msgstr "Lataa"`     Text in desired language.
+
+
+
+

Edit the msgstr

+
+
+

Once edited translations need to be compiled into more efficient format for the web server. This is done by running:

+
+
+
+
podman run -it --rm -v "$(pwd):/opt/:z" fedora-websites ./scripts/translations-compile-local.sh
+
+
+
+

You can now change your browser setting to desired language and see how the translations are working out.

+
+
+
+

Description of translation scripts inside sites/getfedora.org/scripts

+
+ + + + + +
+ + +
+

Technically scripts can be run without using podman, but will then require proper setup in the local machine. The instructions given above are safer for generic users.

+
+
+
+
+
+
+
+
+

These nice people helped write this page:

+

Jan Kuparinen

+

Want to help? Learn how to contribute to Fedora Docs.

+
+
+
+

All Fedora Documentation content available under CC-BY-SA 3.0 or, when specifically noted, under another accepted free and open content license.

+

Last build:

+
+ + + + + diff --git a/docs/site.yml b/docs/site.yml new file mode 100644 index 0000000..b8fdc7f --- /dev/null +++ b/docs/site.yml @@ -0,0 +1,20 @@ +site: + title: Fedora Websites + start_page: websites::index +content: + sources: + - url: . + branches: HEAD +ui: + bundle: + url: https://asamalik.fedorapeople.org/ui-bundle.zip + snapshot: true + default_layout: with_menu +output: + clean: true + dir: ./public + destinations: + - provider: archive +runtime: + pull: true + cache_dir: ./cache From c789731366673b7cbc46e63047021f7b7bddf877 Mon Sep 17 00:00:00 2001 From: Justin W. Flory (he/him) [Fedora Project] Date: Nov 03 2021 15:43:34 +0000 Subject: [PATCH 3/3] docs: Convert docs.fp.o/websites/ to publish from this repository Several changes are condensed into this commit. It takes the base W&A team documentation site, converts into a friendly format for this repository, and modernizes all the existing content there. For posterity's sake, the squashed commit log is below: Signed-off-by: Justin W. Flory (he/him) [Fedora Project] --- * gitignore: Add Antora build caches and output directories * build.sh: Update from pagure.io/fedora-docs/template * antora: Move build scripts to root directory * Add "& Apps" to title, set start_path to docs * This tells the Antora playbook to look into the `docs/` directory for the content to serve. * modules: Split instructional content into new "runbook" module * This will be part of a growing compilation of docs and information about how the Websites & Apps team is run and how we organize ourselves. * runbook: Create an index page and describe role/function of runbook * Rewrite index page * This is a near-complete restructure of the index page for the W&A team. This merges in relevant content and information from the Sphinx docs `index.rst` file with the current `index.adoc` used for the team. * I also restructured the opening and tried to update copy with current information and approaches. Some content was removed if it was no longer made sense in our current form. * runbook: Create dedicated page about team meetings * runbook: Add page-aliases to redirect from old URL namespace * Since these pages existed previously, using the `page-aliases` directive will cause them to redirect to their new location in the `runbook` module. * dev: Create new module from setup documentation * This commit puts together a new module to gather developer content. For now, this just pulls from the content that was already published in the root module. * dev: Add an index page to developer docs * old_docs: Move remaining page from old docs into ROOT module * ROOT: Convert old websites_release ReST doc to AsciiDoc * Not publishing it clearly, but keeping it here for future review by the team to ensure accuracy. * ROOT: Add translation doc page to module navigation * legal: Update to CC BY-SA 4.0 :heart: * This follows the somewhat-recent decision by Fedora to update its Creative Common licensing from 3.0 Unported to 4.0. * README: Add docs.fp.o/websites/ as a site hosted from this repo --- diff --git a/.gitignore b/.gitignore index 7eef366..a1aed87 100644 --- a/.gitignore +++ b/.gitignore @@ -13,3 +13,7 @@ httpd/run/*.pid */out */data/templates/translations.html +# Antora build caches and directories for docs.fp.o +build +cache +public diff --git a/README.md b/README.md index 250aa45..9763823 100644 --- a/README.md +++ b/README.md @@ -12,10 +12,10 @@ from the F24 release cycle. History of previous commits is still available in the [old repo on Fedora Hosted](https://git.fedorahosted.org/cgit/fedora-web.git/). **For more information please read the [documentation](https://docs.pagure.org/fedora-websites/) and the [Fedora Websites pages on the Fedora Wiki](https://fedoraproject.org/wiki/Websites)** ### Contributing -If you like to help the websites team but are not actually a member, you +If you like to help the websites team but are not actually a member, you can easily file Pull Requests. Fork this repository, make your changes and submit them here. Check of the [Fedora Websites wiki](https://fedoraproject.org/wiki/Websites#Join_the_Websites_Team) for details on how to -become a member of the websites team. +become a member of the websites team. Translations are handled by the Fedora [localization team](https://fedoraproject.org/wiki/L10N) on [Fedora Weblate](https://translate.stg.fedoraproject.org/projects/fedora-websites/). @@ -29,6 +29,7 @@ This repository contains the sources for the following Fedora Websites: * http://arm.fedoraproject.org * http://boot.fedoraproject.org * http://budget.fedoraproject.org +* https://docs.fedoraproject.org/en-US/websites/ * http://fedoracommunity.org * http://fedorahosted.org * http://fedorapeople.org diff --git a/build.sh b/build.sh new file mode 100755 index 0000000..75dd387 --- /dev/null +++ b/build.sh @@ -0,0 +1,51 @@ +#!/bin/sh + +image="docker.io/antora/antora" +cmd="--html-url-extension-style=indexify site.yml" + +if [ "$(uname)" == "Darwin" ]; then + # Running on macOS. + # Let's assume that the user has the Docker CE installed + # which doesn't require a root password. + echo "" + echo "This build script is using Docker container runtime to run the build in an isolated environment." + echo "" + docker run --rm -it -v $(pwd):/antora $image $cmd + +elif [ "$(expr substr $(uname -s) 1 5)" == "Linux" ]; then + # Running on Linux. + # there isn't an antora/aarch64 container, antora can be installed locally + # Check whether podman is available, else faill back to docker + # which requires root. + + if [ -f /usr/local/bin/antora ]; then + /usr/local/bin/antora $cmd + elif [[ `uname -m` == "aarch64" ]]; then + echo "no antora/aarch64 container try just \`npm install -g @antora/cli @antora/site-generator-default\`" + elif [ -f /usr/bin/podman ]; then + echo "" + echo "This build script is using Podman to run the build in an isolated environment." + echo "" + podman run --rm -it -v $(pwd):/antora:z $image $cmd + + elif [ -f /usr/bin/docker ]; then + echo "" + echo "This build script is using Docker to run the build in an isolated environment." + echo "" + + if groups | grep -wq "docker"; then + docker run --rm -it -v $(pwd):/antora:z $image $cmd + else + echo "" + echo "This build script is using $runtime to run the build in an isolated environment. You might be asked for your password." + echo "You can avoid this by adding your user to the 'docker' group, but be aware of the security implications. See https://docs.docker.com/install/linux/linux-postinstall/." + echo "" + sudo docker run --rm -it -v $(pwd):/antora:z $image $cmd + fi + else + echo "" + echo "Error: Container runtime haven't been found on your system. Fix it by:" + echo "$ sudo dnf install podman" + exit 1 + fi +fi diff --git a/docs/LICENSE b/docs/LICENSE deleted file mode 100644 index 1495fc1..0000000 --- a/docs/LICENSE +++ /dev/null @@ -1,360 +0,0 @@ -Creative Commons Legal Code - -Attribution-ShareAlike 3.0 Unported - - CREATIVE COMMONS CORPORATION IS NOT A LAW FIRM AND DOES NOT PROVIDE - LEGAL SERVICES. DISTRIBUTION OF THIS LICENSE DOES NOT CREATE AN - ATTORNEY-CLIENT RELATIONSHIP. CREATIVE COMMONS PROVIDES THIS - INFORMATION ON AN "AS-IS" BASIS. CREATIVE COMMONS MAKES NO WARRANTIES - REGARDING THE INFORMATION PROVIDED, AND DISCLAIMS LIABILITY FOR - DAMAGES RESULTING FROM ITS USE. - -License - -THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE -COMMONS PUBLIC LICENSE ("CCPL" OR "LICENSE"). THE WORK IS PROTECTED BY -COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS -AUTHORIZED UNDER THIS LICENSE OR COPYRIGHT LAW IS PROHIBITED. - -BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE -TO BE BOUND BY THE TERMS OF THIS LICENSE. TO THE EXTENT THIS LICENSE MAY -BE CONSIDERED TO BE A CONTRACT, THE LICENSOR GRANTS YOU THE RIGHTS -CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND -CONDITIONS. - -1. Definitions - - a. "Adaptation" means a work based upon the Work, or upon the Work and - other pre-existing works, such as a translation, adaptation, - derivative work, arrangement of music or other alterations of a - literary or artistic work, or phonogram or performance and includes - cinematographic adaptations or any other form in which the Work may be - recast, transformed, or adapted including in any form recognizably - derived from the original, except that a work that constitutes a - Collection will not be considered an Adaptation for the purpose of - this License. For the avoidance of doubt, where the Work is a musical - work, performance or phonogram, the synchronization of the Work in - timed-relation with a moving image ("synching") will be considered an - Adaptation for the purpose of this License. - b. "Collection" means a collection of literary or artistic works, such as - encyclopedias and anthologies, or performances, phonograms or - broadcasts, or other works or subject matter other than works listed - in Section 1(f) below, which, by reason of the selection and - arrangement of their contents, constitute intellectual creations, in - which the Work is included in its entirety in unmodified form along - with one or more other contributions, each constituting separate and - independent works in themselves, which together are assembled into a - collective whole. A work that constitutes a Collection will not be - considered an Adaptation (as defined below) for the purposes of this - License. - c. "Creative Commons Compatible License" means a license that is listed - at https://creativecommons.org/compatiblelicenses that has been - approved by Creative Commons as being essentially equivalent to this - License, including, at a minimum, because that license: (i) contains - terms that have the same purpose, meaning and effect as the License - Elements of this License; and, (ii) explicitly permits the relicensing - of adaptations of works made available under that license under this - License or a Creative Commons jurisdiction license with the same - License Elements as this License. - d. "Distribute" means to make available to the public the original and - copies of the Work or Adaptation, as appropriate, through sale or - other transfer of ownership. - e. "License Elements" means the following high-level license attributes - as selected by Licensor and indicated in the title of this License: - Attribution, ShareAlike. - f. "Licensor" means the individual, individuals, entity or entities that - offer(s) the Work under the terms of this License. - g. "Original Author" means, in the case of a literary or artistic work, - the individual, individuals, entity or entities who created the Work - or if no individual or entity can be identified, the publisher; and in - addition (i) in the case of a performance the actors, singers, - musicians, dancers, and other persons who act, sing, deliver, declaim, - play in, interpret or otherwise perform literary or artistic works or - expressions of folklore; (ii) in the case of a phonogram the producer - being the person or legal entity who first fixes the sounds of a - performance or other sounds; and, (iii) in the case of broadcasts, the - organization that transmits the broadcast. - h. "Work" means the literary and/or artistic work offered under the terms - of this License including without limitation any production in the - literary, scientific and artistic domain, whatever may be the mode or - form of its expression including digital form, such as a book, - pamphlet and other writing; a lecture, address, sermon or other work - of the same nature; a dramatic or dramatico-musical work; a - choreographic work or entertainment in dumb show; a musical - composition with or without words; a cinematographic work to which are - assimilated works expressed by a process analogous to cinematography; - a work of drawing, painting, architecture, sculpture, engraving or - lithography; a photographic work to which are assimilated works - expressed by a process analogous to photography; a work of applied - art; an illustration, map, plan, sketch or three-dimensional work - relative to geography, topography, architecture or science; a - performance; a broadcast; a phonogram; a compilation of data to the - extent it is protected as a copyrightable work; or a work performed by - a variety or circus performer to the extent it is not otherwise - considered a literary or artistic work. - i. "You" means an individual or entity exercising rights under this - License who has not previously violated the terms of this License with - respect to the Work, or who has received express permission from the - Licensor to exercise rights under this License despite a previous - violation. - j. "Publicly Perform" means to perform public recitations of the Work and - to communicate to the public those public recitations, by any means or - process, including by wire or wireless means or public digital - performances; to make available to the public Works in such a way that - members of the public may access these Works from a place and at a - place individually chosen by them; to perform the Work to the public - by any means or process and the communication to the public of the - performances of the Work, including by public digital performance; to - broadcast and rebroadcast the Work by any means including signs, - sounds or images. - k. "Reproduce" means to make copies of the Work by any means including - without limitation by sound or visual recordings and the right of - fixation and reproducing fixations of the Work, including storage of a - protected performance or phonogram in digital form or other electronic - medium. - -2. Fair Dealing Rights. Nothing in this License is intended to reduce, -limit, or restrict any uses free from copyright or rights arising from -limitations or exceptions that are provided for in connection with the -copyright protection under copyright law or other applicable laws. - -3. License Grant. Subject to the terms and conditions of this License, -Licensor hereby grants You a worldwide, royalty-free, non-exclusive, -perpetual (for the duration of the applicable copyright) license to -exercise the rights in the Work as stated below: - - a. to Reproduce the Work, to incorporate the Work into one or more - Collections, and to Reproduce the Work as incorporated in the - Collections; - b. to create and Reproduce Adaptations provided that any such Adaptation, - including any translation in any medium, takes reasonable steps to - clearly label, demarcate or otherwise identify that changes were made - to the original Work. For example, a translation could be marked "The - original work was translated from English to Spanish," or a - modification could indicate "The original work has been modified."; - c. to Distribute and Publicly Perform the Work including as incorporated - in Collections; and, - d. to Distribute and Publicly Perform Adaptations. - e. For the avoidance of doubt: - - i. Non-waivable Compulsory License Schemes. In those jurisdictions in - which the right to collect royalties through any statutory or - compulsory licensing scheme cannot be waived, the Licensor - reserves the exclusive right to collect such royalties for any - exercise by You of the rights granted under this License; - ii. Waivable Compulsory License Schemes. In those jurisdictions in - which the right to collect royalties through any statutory or - compulsory licensing scheme can be waived, the Licensor waives the - exclusive right to collect such royalties for any exercise by You - of the rights granted under this License; and, - iii. Voluntary License Schemes. The Licensor waives the right to - collect royalties, whether individually or, in the event that the - Licensor is a member of a collecting society that administers - voluntary licensing schemes, via that society, from any exercise - by You of the rights granted under this License. - -The above rights may be exercised in all media and formats whether now -known or hereafter devised. The above rights include the right to make -such modifications as are technically necessary to exercise the rights in -other media and formats. Subject to Section 8(f), all rights not expressly -granted by Licensor are hereby reserved. - -4. Restrictions. The license granted in Section 3 above is expressly made -subject to and limited by the following restrictions: - - a. You may Distribute or Publicly Perform the Work only under the terms - of this License. You must include a copy of, or the Uniform Resource - Identifier (URI) for, this License with every copy of the Work You - Distribute or Publicly Perform. You may not offer or impose any terms - on the Work that restrict the terms of this License or the ability of - the recipient of the Work to exercise the rights granted to that - recipient under the terms of the License. You may not sublicense the - Work. You must keep intact all notices that refer to this License and - to the disclaimer of warranties with every copy of the Work You - Distribute or Publicly Perform. When You Distribute or Publicly - Perform the Work, You may not impose any effective technological - measures on the Work that restrict the ability of a recipient of the - Work from You to exercise the rights granted to that recipient under - the terms of the License. This Section 4(a) applies to the Work as - incorporated in a Collection, but this does not require the Collection - apart from the Work itself to be made subject to the terms of this - License. If You create a Collection, upon notice from any Licensor You - must, to the extent practicable, remove from the Collection any credit - as required by Section 4(c), as requested. If You create an - Adaptation, upon notice from any Licensor You must, to the extent - practicable, remove from the Adaptation any credit as required by - Section 4(c), as requested. - b. You may Distribute or Publicly Perform an Adaptation only under the - terms of: (i) this License; (ii) a later version of this License with - the same License Elements as this License; (iii) a Creative Commons - jurisdiction license (either this or a later license version) that - contains the same License Elements as this License (e.g., - Attribution-ShareAlike 3.0 US)); (iv) a Creative Commons Compatible - License. If you license the Adaptation under one of the licenses - mentioned in (iv), you must comply with the terms of that license. If - you license the Adaptation under the terms of any of the licenses - mentioned in (i), (ii) or (iii) (the "Applicable License"), you must - comply with the terms of the Applicable License generally and the - following provisions: (I) You must include a copy of, or the URI for, - the Applicable License with every copy of each Adaptation You - Distribute or Publicly Perform; (II) You may not offer or impose any - terms on the Adaptation that restrict the terms of the Applicable - License or the ability of the recipient of the Adaptation to exercise - the rights granted to that recipient under the terms of the Applicable - License; (III) You must keep intact all notices that refer to the - Applicable License and to the disclaimer of warranties with every copy - of the Work as included in the Adaptation You Distribute or Publicly - Perform; (IV) when You Distribute or Publicly Perform the Adaptation, - You may not impose any effective technological measures on the - Adaptation that restrict the ability of a recipient of the Adaptation - from You to exercise the rights granted to that recipient under the - terms of the Applicable License. This Section 4(b) applies to the - Adaptation as incorporated in a Collection, but this does not require - the Collection apart from the Adaptation itself to be made subject to - the terms of the Applicable License. - c. If You Distribute, or Publicly Perform the Work or any Adaptations or - Collections, You must, unless a request has been made pursuant to - Section 4(a), keep intact all copyright notices for the Work and - provide, reasonable to the medium or means You are utilizing: (i) the - name of the Original Author (or pseudonym, if applicable) if supplied, - and/or if the Original Author and/or Licensor designate another party - or parties (e.g., a sponsor institute, publishing entity, journal) for - attribution ("Attribution Parties") in Licensor's copyright notice, - terms of service or by other reasonable means, the name of such party - or parties; (ii) the title of the Work if supplied; (iii) to the - extent reasonably practicable, the URI, if any, that Licensor - specifies to be associated with the Work, unless such URI does not - refer to the copyright notice or licensing information for the Work; - and (iv) , consistent with Ssection 3(b), in the case of an - Adaptation, a credit identifying the use of the Work in the Adaptation - (e.g., "French translation of the Work by Original Author," or - "Screenplay based on original Work by Original Author"). The credit - required by this Section 4(c) may be implemented in any reasonable - manner; provided, however, that in the case of a Adaptation or - Collection, at a minimum such credit will appear, if a credit for all - contributing authors of the Adaptation or Collection appears, then as - part of these credits and in a manner at least as prominent as the - credits for the other contributing authors. For the avoidance of - doubt, You may only use the credit required by this Section for the - purpose of attribution in the manner set out above and, by exercising - Your rights under this License, You may not implicitly or explicitly - assert or imply any connection with, sponsorship or endorsement by the - Original Author, Licensor and/or Attribution Parties, as appropriate, - of You or Your use of the Work, without the separate, express prior - written permission of the Original Author, Licensor and/or Attribution - Parties. - d. Except as otherwise agreed in writing by the Licensor or as may be - otherwise permitted by applicable law, if You Reproduce, Distribute or - Publicly Perform the Work either by itself or as part of any - Adaptations or Collections, You must not distort, mutilate, modify or - take other derogatory action in relation to the Work which would be - prejudicial to the Original Author's honor or reputation. Licensor - agrees that in those jurisdictions (e.g. Japan), in which any exercise - of the right granted in Section 3(b) of this License (the right to - make Adaptations) would be deemed to be a distortion, mutilation, - modification or other derogatory action prejudicial to the Original - Author's honor and reputation, the Licensor will waive or not assert, - as appropriate, this Section, to the fullest extent permitted by the - applicable national law, to enable You to reasonably exercise Your - right under Section 3(b) of this License (right to make Adaptations) - but not otherwise. - -5. Representations, Warranties and Disclaimer - -UNLESS OTHERWISE MUTUALLY AGREED TO BY THE PARTIES IN WRITING, LICENSOR -OFFERS THE WORK AS-IS AND MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY -KIND CONCERNING THE WORK, EXPRESS, IMPLIED, STATUTORY OR OTHERWISE, -INCLUDING, WITHOUT LIMITATION, WARRANTIES OF TITLE, MERCHANTIBILITY, -FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT, OR THE ABSENCE OF -LATENT OR OTHER DEFECTS, ACCURACY, OR THE PRESENCE OF ABSENCE OF ERRORS, -WHETHER OR NOT DISCOVERABLE. SOME JURISDICTIONS DO NOT ALLOW THE EXCLUSION -OF IMPLIED WARRANTIES, SO SUCH EXCLUSION MAY NOT APPLY TO YOU. - -6. Limitation on Liability. EXCEPT TO THE EXTENT REQUIRED BY APPLICABLE -LAW, IN NO EVENT WILL LICENSOR BE LIABLE TO YOU ON ANY LEGAL THEORY FOR -ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, PUNITIVE OR EXEMPLARY DAMAGES -ARISING OUT OF THIS LICENSE OR THE USE OF THE WORK, EVEN IF LICENSOR HAS -BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. - -7. Termination - - a. This License and the rights granted hereunder will terminate - automatically upon any breach by You of the terms of this License. - Individuals or entities who have received Adaptations or Collections - from You under this License, however, will not have their licenses - terminated provided such individuals or entities remain in full - compliance with those licenses. Sections 1, 2, 5, 6, 7, and 8 will - survive any termination of this License. - b. Subject to the above terms and conditions, the license granted here is - perpetual (for the duration of the applicable copyright in the Work). - Notwithstanding the above, Licensor reserves the right to release the - Work under different license terms or to stop distributing the Work at - any time; provided, however that any such election will not serve to - withdraw this License (or any other license that has been, or is - required to be, granted under the terms of this License), and this - License will continue in full force and effect unless terminated as - stated above. - -8. Miscellaneous - - a. Each time You Distribute or Publicly Perform the Work or a Collection, - the Licensor offers to the recipient a license to the Work on the same - terms and conditions as the license granted to You under this License. - b. Each time You Distribute or Publicly Perform an Adaptation, Licensor - offers to the recipient a license to the original Work on the same - terms and conditions as the license granted to You under this License. - c. If any provision of this License is invalid or unenforceable under - applicable law, it shall not affect the validity or enforceability of - the remainder of the terms of this License, and without further action - by the parties to this agreement, such provision shall be reformed to - the minimum extent necessary to make such provision valid and - enforceable. - d. No term or provision of this License shall be deemed waived and no - breach consented to unless such waiver or consent shall be in writing - and signed by the party to be charged with such waiver or consent. - e. This License constitutes the entire agreement between the parties with - respect to the Work licensed here. There are no understandings, - agreements or representations with respect to the Work not specified - here. Licensor shall not be bound by any additional provisions that - may appear in any communication from You. This License may not be - modified without the mutual written agreement of the Licensor and You. - f. The rights granted under, and the subject matter referenced, in this - License were drafted utilizing the terminology of the Berne Convention - for the Protection of Literary and Artistic Works (as amended on - September 28, 1979), the Rome Convention of 1961, the WIPO Copyright - Treaty of 1996, the WIPO Performances and Phonograms Treaty of 1996 - and the Universal Copyright Convention (as revised on July 24, 1971). - These rights and subject matter take effect in the relevant - jurisdiction in which the License terms are sought to be enforced - according to the corresponding provisions of the implementation of - those treaty provisions in the applicable national law. If the - standard suite of rights granted under applicable copyright law - includes additional rights not granted under this License, such - additional rights are deemed to be included in the License; this - License is not intended to restrict the license of any rights under - applicable law. - - -Creative Commons Notice - - Creative Commons is not a party to this License, and makes no warranty - whatsoever in connection with the Work. Creative Commons will not be - liable to You or any party on any legal theory for any damages - whatsoever, including without limitation any general, special, - incidental or consequential damages arising in connection to this - license. Notwithstanding the foregoing two (2) sentences, if Creative - Commons has expressly identified itself as the Licensor hereunder, it - shall have all rights and obligations of Licensor. - - Except for the limited purpose of indicating to the public that the - Work is licensed under the CCPL, Creative Commons does not authorize - the use by either party of the trademark "Creative Commons" or any - related trademark or logo of Creative Commons without the prior - written consent of Creative Commons. Any permitted use will be in - compliance with Creative Commons' then-current trademark usage - guidelines, as may be published on its website or otherwise made - available upon request from time to time. For the avoidance of doubt, - this trademark restriction does not form part of the License. - - Creative Commons may be contacted at https://creativecommons.org/. - diff --git a/docs/LICENSE.txt b/docs/LICENSE.txt new file mode 100644 index 0000000..a73481c --- /dev/null +++ b/docs/LICENSE.txt @@ -0,0 +1,428 @@ +Attribution-ShareAlike 4.0 International + +======================================================================= + +Creative Commons Corporation ("Creative Commons") is not a law firm and +does not provide legal services or legal advice. Distribution of +Creative Commons public licenses does not create a lawyer-client or +other relationship. Creative Commons makes its licenses and related +information available on an "as-is" basis. Creative Commons gives no +warranties regarding its licenses, any material licensed under their +terms and conditions, or any related information. Creative Commons +disclaims all liability for damages resulting from their use to the +fullest extent possible. + +Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and +conditions that creators and other rights holders may use to share +original works of authorship and other material subject to copyright +and certain other rights specified in the public license below. The +following considerations are for informational purposes only, are not +exhaustive, and do not form part of our licenses. + + Considerations for licensors: Our public licenses are + intended for use by those authorized to give the public + permission to use material in ways otherwise restricted by + copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms + and conditions of the license they choose before applying it. + Licensors should also secure all rights necessary before + applying our licenses so that the public can reuse the + material as expected. Licensors should clearly mark any + material not subject to the license. This includes other CC- + licensed material, or material used under an exception or + limitation to copyright. More considerations for licensors: + wiki.creativecommons.org/Considerations_for_licensors + + Considerations for the public: By using one of our public + licenses, a licensor grants the public permission to use the + licensed material under specified terms and conditions. If + the licensor's permission is not necessary for any reason--for + example, because of any applicable exception or limitation to + copyright--then that use is not regulated by the license. Our + licenses grant only permissions under copyright and certain + other rights that a licensor has authority to grant. Use of + the licensed material may still be restricted for other + reasons, including because others have copyright or other + rights in the material. A licensor may make special requests, + such as asking that all changes be marked or described. + Although not required by our licenses, you are encouraged to + respect those requests where reasonable. More considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees + +======================================================================= + +Creative Commons Attribution-ShareAlike 4.0 International Public +License + +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution-ShareAlike 4.0 International Public License ("Public +License"). To the extent this Public License may be interpreted as a +contract, You are granted the Licensed Rights in consideration of Your +acceptance of these terms and conditions, and the Licensor grants You +such rights in consideration of benefits the Licensor receives from +making the Licensed Material available under these terms and +conditions. + + +Section 1 -- Definitions. + + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. + + c. BY-SA Compatible License means a license listed at + creativecommons.org/compatiblelicenses, approved by Creative + Commons as essentially the equivalent of this Public License. + + d. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + + e. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + + f. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + + g. License Elements means the license attributes listed in the name + of a Creative Commons Public License. The License Elements of this + Public License are Attribution and ShareAlike. + + h. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + + i. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + + j. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. + + k. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + + l. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + + m. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + + +Section 2 -- Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: + + a. reproduce and Share the Licensed Material, in whole or + in part; and + + b. produce, reproduce, and Share Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + + 3. Term. The term of this Public License is specified in Section + 6(a). + + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. Additional offer from the Licensor -- Adapted Material. + Every recipient of Adapted Material from You + automatically receives an offer from the Licensor to + exercise the Licensed Rights in the Adapted Material + under the conditions of the Adapter's License You apply. + + c. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified + form), You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + b. ShareAlike. + + In addition to the conditions in Section 3(a), if You Share + Adapted Material You produce, the following conditions also apply. + + 1. The Adapter's License You apply must be a Creative Commons + license with the same License Elements, this version or + later, or a BY-SA Compatible License. + + 2. You must include the text of, or the URI or hyperlink to, the + Adapter's License You apply. You may satisfy this condition + in any reasonable manner based on the medium, means, and + context in which You Share Adapted Material. + + 3. You may not offer or impose any additional or different terms + or conditions on, or apply any Effective Technological + Measures to, Adapted Material that restrict exercise of the + rights granted under the Adapter's License You apply. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material, + + including for purposes of Section 3(b); and + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + + +======================================================================= + +Creative Commons is not a party to its public +licenses. Notwithstanding, Creative Commons may elect to apply one of +its public licenses to material it publishes and in those instances +will be considered the “Licensor.” The text of the Creative Commons +public licenses is dedicated to the public domain under the CC0 Public +Domain Dedication. Except for the limited purpose of indicating that +material is shared under a Creative Commons public license or as +otherwise permitted by the Creative Commons policies published at +creativecommons.org/policies, Creative Commons does not authorize the +use of the trademark "Creative Commons" or any other trademark or logo +of Creative Commons without its prior written consent including, +without limitation, in connection with any unauthorized modifications +to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For +the avoidance of doubt, this paragraph does not form part of the +public licenses. + +Creative Commons may be contacted at creativecommons.org. + diff --git a/docs/antora.yml b/docs/antora.yml index 009c240..1c3499b 100644 --- a/docs/antora.yml +++ b/docs/antora.yml @@ -3,7 +3,7 @@ name: websites # Title will be visible on the page. -title: Fedora Websites +title: Fedora Websites & Apps # If you don't plan to have multiple versions of the docs (for example, to document multiple versions of some software), you can ignore this field. Otherwise, change "master" to a specific version. version: master @@ -14,3 +14,5 @@ start_page: ROOT:index # This lists all the menu definitions of your component. nav: - modules/ROOT/nav.adoc +- modules/runbook/nav.adoc +- modules/dev/nav.adoc diff --git a/docs/build.sh b/docs/build.sh deleted file mode 100755 index f4ecfe4..0000000 --- a/docs/build.sh +++ /dev/null @@ -1,46 +0,0 @@ -#!/bin/sh - -image="docker.io/antora/antora" -cmd="--html-url-extension-style=indexify site.yml" - -if [ "$(uname)" = "Darwin" ]; then - # Running on macOS. - # Let's assume that the user has the Docker CE installed - # which doesn't require a root password. - echo "" - echo "This build script is using Docker container runtime to run the build in an isolated environment." - echo "" - docker run --rm -it -v "$(pwd):/antora" $image $cmd - -elif [ "$(expr substr "$(uname -s)" 1 5)" = "Linux" ]; then - # Running on Linux. - # Check whether podman is available, else fall back to docker - # which requires root. - - if [ -f /usr/bin/podman ]; then - echo "" - echo "This build script is using Podman to run the build in an isolated environment." - echo "" - podman run --rm -it -v "$(pwd):/antora:z" $image $cmd - - elif [ -f /usr/bin/docker ]; then - echo "" - echo "This build script is using Docker to run the build in an isolated environment." - echo "" - - if groups | grep -wq "docker"; then - docker run --rm -it -v "$(pwd):/antora:z" $image $cmd - else - echo "" - echo "This build script is using $runtime to run the build in an isolated environment. You might be asked for your password." - echo "You can avoid this by adding your user to the 'docker' group, but be aware of the security implications. See https://docs.docker.com/install/linux/linux-postinstall/." - echo "" - sudo docker run --rm -it -v "$(pwd):/antora:z" $image $cmd - fi - else - echo "" - echo "Error: Container runtime haven't been found on your system. Fix it by:" - echo "$ sudo dnf install podman" - exit 1 - fi -fi diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 6d0a691..cc60b23 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1,6 +1,2 @@ -* xref:setup-docker.adoc[Getting Set Up (Docker)] -* xref:setup.adoc[Getting Set Up (old method)] * xref:fedora-release.adoc[Fedora Beta/GA Release] -* xref:newcontent.adoc[Creating New Content] -** xref:newcontent-edition.adoc[New Edition] -** xref:newcontent-site.adoc[New Site] +* xref:translation-flow.adoc[Translation flow] diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index cd940a4..c95db73 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -1,43 +1,106 @@ -= Fedora Websites -Rick Elrod; Ryan Lerch -:page-authors: {author}, {author_2} +include::ROOT:partial$attributes.adoc[] -== Who We Are -The Fedora Websites & Apps team works on the frontend and backend of Fedora's websites and web applications. -This team is a reboot of the previous Fedora Website's team, created by community members to update and improve Fedora's web presence and online documentation. += Fedora Websites & Apps +Rick Elrod; Ryan Lerch, Justin W. Flory +:page-authors: {author}, {author_2}, {author_3} +:toc: -We are a growing team of developers with a range of skills and interests. One of our team's first goals is to set up the foundation of an empowering mentorship program. +Welcome to the official documentation for the Fedora Websites & Apps Team. -== Our Collaborations -Working on both websites and web applications, our team is regularly communicating and working with different stakeholders in Fedora's community. -* We work closely with the link:++https://fedoraproject.org/wiki/Design++[Fedora Design team] to build our websites that are visually pleasing, easy to use, and accessible to everybody. -* Along with the design team, we also work closely with link:++https://fedoraproject.org/wiki/Infrastructure++[Fedora Infrastructure] on backend technologies. -* We also collaborate with the link:++https://fedoraproject.org/wiki/L10N++[Fedora Translations team] to ensure that websites are able to be translated into different languages. -* Typically has one member (either in Design or Websites) who sits on the - xref:mindshare::index.adoc[Fedora Mindshare committee]. +[[about]] +== About our team -== What We Do -The W&A Team updates and maintains the code bases for Fedora's websites and web applications. We collaborate closely with the Fedora Design team and Fedora Infrastructure to implement new designs and update backend code. The W&A team is regularly working on a variety of tasks that are suitable for new and experienced contributors. +The Fedora Websites & Apps Team improves Fedora's image and creates user-friendly interfaces for users and contributors on the Internet. +We are a community-led team compromised of contributors from around the world. +The key goals of the team includes the following activities: + +* Consolidate key Fedora Project websites into a single uniform scheme. +* Develop front-end and back-end components of Fedora's online web applications. +* Maintain content that doesn't fall under any particular sub-project. +* Generally, making the sites as fun and exciting as the project they represent! + +[[about-revamp]] +=== Websites & Apps Community Revamp Objective + +The team was rebooted in 2021 as part of the https://fedoraproject.org/wiki/Objectives/Websites_%26_Apps_Community_Revamp[Websites & Apps Community Revamp Objective]. +We are a growing team of developers with a range of skills and interests. +This Objective started for a few reasons: + +* Better coordination to facilitate a growing interest in Fedora's web presence +* Involving diverse contributors to take part in a knowledgeable group helping maintain the Fedora Project's websites and apps in line with modern web standards. + + +[[collaborations]] +== Our collaborations + +In order to work in a community with as many diverse projects and stakeholders as the Fedora Project, our team aims to communicate regularly with different community members in Fedora. +Work on specific websites is coordinated by the appropriate sub-projects and/or project lead(s). + +Here is a list of our frequent collaborators: + +[[collaborations-fedora]] +=== Fedora sub-projects + +* https://fedoraproject.org/wiki/Design[*Design Team*]: + Create designs, wireframes, and other visual content to guide development efforts +* *Infrastructure*: + Support on back-end technologies and hosting official Fedora Project infrastructure. +* *Localization Team*: + Translates strings across Fedora websites and apps into different languages. +* xref:mindshare::index.adoc[*Mindshare Committee*]: + W&A Team holds one seat on the Fedora Mindshare Committee. + +[[collaborations-friends]] +=== Friends of Fedora + +* xref:cpe::index.adoc[*Red Hat Community Platform Engineering* (CPE)]: + A Red Hat team dedicated to the Fedora and CentOS projects where they contribute to the infrastructure and release engineering. +* https://www.redhat.com/en/blog/channel/red-hat-open-source-program-office[*Red Hat Open Source Program Office engineers*]: + A Red Hat team that supports various Open Source technology initiatives across the Red Hat technology ecosystem. + + +[[work]] +== Our work + +The W&A Team updates and maintains the code bases for Fedora's websites and web applications. +We work on a variety of tasks suitable for both new and experienced contributors. + +[[work-tasks]] +=== Example tasks -=== Tasks Include: * Adding temporary content to websites * Coding design mockups provided by the Design Team -* Updating server side code -* Improving language and accessiblity support +* Updating server-side code +* Improving language and accessibility support * Revamping websites to improve user experience -* Writing documentation for contributors +* Writing documentation for contributors -=== The Web and Apps Team Revamp -In 2021, the Fedora Websites Team began a revamp into the Fedora Websites & Apps Team. This was was started in order to facilitate the growing interest in Fedora's web presence as well as a need for a knowledgeable group of contributors to focus on keeping Fedora's websites and apps up to date current with modern web standards. -== How To Get Involved +[[bug]] +== Report a bug -To get involved with the Fedora W&A team get in touch with us through the email list or by messaging us on Telegram. We are looking for both front and backend contributors of all skill levels. If you are interested in getting active, feel free to check out the open tickets on pagure. +Find a bug on one of our websites? +See https://fedoraproject.org/wiki/How_to_fix_bugs_on_the_Fedora_Project_website[these instructions on fixing bugs]. +Otherwise please report them on our https://pagure.io/fedora-websites[Pagure repository]. -We also welcome new contributors to our weekly meetings. If you have something that you would like to address, send a message to one of our team leads ahead of time so that we can plan to discuss your topic at an upcomming session. -=== Membership + +[[contact]] +== Contact us + +Have questions or want to know more? +Get in touch with our team in the following places: + +* *Asynchronous*: +** link:++{COMMS-DISCOURSE}++[Fedora Discussion] +** link:++{COMMS-LISTSERV}++[Mailing list] +* *Synchronous*: +** link:++ircs://{COMMS-IRC-SERVER}:{COMMS-IRC-SERVER-PORT}/{COMMS-IRC}++[IRC] +** link:++{COMMS-MATRIX}++[Matrix] +** link:++{COMMS-TELEGRAM}++[Telegram] + +== Membership In order to become a member of the Fedora Website & Apps Team, the applicant must be register at link:++https://accounts.fedoraproject.org++[Fedora Accounts] and set up an account with the link:++https://pagure.io++[Pagure] gitforge. @@ -46,45 +109,29 @@ By becoming a Fedora Contributor, you accept these terms. * link:++https://fedoraproject.org/wiki/Legal:Fedora_Project_Contributor_Agreement++[Fedora Project Contributor Agrement (FPCA)] * link:++https://docs.fedoraproject.org/en-US/project/code-of-conduct/++[Code of Conduct] -=== Are You New to Web Development? +== Are You New to Web Development? We flag tickets that are suitable for new contributors and those whom are newer to html, css, js, and python. If you aren't sure where to start, or cannot find documentation that you are looking for, get in touch with one of our team members and they will help point you in the right direction. One of the goals of our revamp is to offer mentorship to those who are new to the field, or just interested in advancing their skills. If you are interested in mentorship, get in touch with one of our admins and they will help connect you with someone for mentorship opportunities. -=== Are you an experienced Web Developer? +== Are you an experienced Web Developer? We often have tickets that demand more advanced knowledge of the technologies in our stack, and as web development is such a fast moving field, we are always interested to work with developers that bring something new to the table. Do you see something that you would like to work on? Please get in touch with us. -== Meetings -We hold weekly meetings to review tickets and other tasks, touch base on direction, check in with one another, discuss team direction, and plan activities. Feel free to join us and get involved or to come and ask any questions that you have. We are a diverse team that is always looking for new contributors. - -* Location: link:++https://meet.jit.si/fedora-websites-apps-meeting++[Jitsi Room] -* Day: Tuesdays -* Time: 15:00 - 16:00 UTC - -=== Communication Channels -The W&A Team has a couple different lines of communication. Get in touch with us in any of the following ways (most being connected together): - -* link:++https://t.me/joinchat/hWQIgi7L79k3Nzk5++[Telegram]: Fedora Websites and Apps Telegram Group -* link:++https://discussion.fedoraproject.org/c/project/websites/66++[Discussion Forum]: Public Discussion Space -* link:++https://lists.fedoraproject.org/archives/list/websites@lists.fedoraproject.org/++[Email List]: Announcements, new member introductions -* link:++https://matrix.to/#/#fedora-websites:matrix.org++[Matrix]: Fedora Websites and Apps Matrix Channel -* link:++ircs://irc.libera.chat:6697/#fedora-websites++[IRC]: Fedora Websites and App IRC Channel - -== Resources -The W&A Team is made up of people who work on all levels of the tech stack. We value perspectives and experience from all positions of the tech stack. Check out these resources for your own setup. We are always working to expand our instructional material and documentation. - -=== Fedora's Website Tech Stacks +== Fedora's Website Tech Stacks * Fedora Community Blog: Wordpress * Fedora Websites: Flask, Jinja, HTML, CSS3, JavaScript, Python 3 * Fedora Docs: Asciidoc +== Resources +The W&A Team is made up of people who work on all levels of the tech stack. We value perspectives and experience from all positions of the tech stack. Check out these resources for your own setup. We are always working to expand our instructional material and documentation. + === Documentation * link:++https://fedoraproject.org/w/uploads/1/19/Websitesandappsrevamp_logicmodel.png++[Fedora Websites Revamp Logic Model]: An overview of the Websites Team revamp * link:++https://developer.fedoraproject.org/tech/languages/python/python-installation.html++[Fedora Developer Python] * link:++https://developer.fedoraproject.org/tech/languages/python/flask-installation.html++[Fedora Developer Flask] * For those interested in php and working with the link:++https://communityblog.fedoraproject.org++[Fedora Community Blog] * link:++https://fedoramagazine.org/howto-install-wordpress-fedora/++[Wordpress Local Setup Instructions]: This article will help you setup a local wordpress deployment on Fedora. - + == Code Repositories * link:++https://pagure.io/fedora-websites++[Fedora Websites] * link:++https://pagure.io/fedora-web/websites/++[Fedora Main Website] diff --git a/docs/modules/ROOT/pages/newcontent-edition.adoc b/docs/modules/ROOT/pages/newcontent-edition.adoc deleted file mode 100644 index f6fd5db..0000000 --- a/docs/modules/ROOT/pages/newcontent-edition.adoc +++ /dev/null @@ -1,89 +0,0 @@ -= New Edition -Rick Elrod -:page-authors: {author} - -== Introduction - -Fedora editions are "versions" of Fedora that users can install. These include -"official" editions (Workstation and Server at time of writing), but the -ultimate goal in Websites is to also make Spins and Labs editions be considered -"editions" in some form as far as websites are concerned. That is to say, we'd -like to ultimately have Spins and Labs have a section on the main getfedora.org -site, rendering link:https://spins.fedorparoject.org/[] and -link:https://labs.fedoraproject.org/[] useless and able to be gotten rid of. -Doing this effectively will take some time. - -Also note that most of the content in this document applies to adding pages in -general, with the notable exception of the `release.yaml` edits. Adding a page -to getfedora.org should follow largely the same process, though. - -[NOTE] -==== -All new editions should be added to getfedora.org, to aid in our goal of getting -rid of all of the `*.fedoraproject.org` edition-specific subdomain sites. This -generates a more consistent and less confusing user experience and makes -maintenance of the websites easier going forward. Everything in this document -assumes that you are working with the getfedora.org codebase, and NOT creating a -new site from scratch. -==== - -Now then, all work in this document takes place in the repository in which -link:https://pagure.io/fedora-web/websites/[getfedora.org] lives, and particularly -in the `sites/getfedora.org/` directory. - -== Edition-specific Release Variables - -The first step is to edit `release.yaml`, and add the relevant sections under -`ga` and `beta` for your new edition. Use `workstation` and `server` as -templates. You might not need all variables that these existing sections have, -or you might need to add new ones, depending on your templates, but these blocks -should get you started. - -== Exporting the Edition Routes - -Now, open `main.py` and go to near the bottom, where you'll note a number of -`export_route(...)` calls. This method is a custom method defined earlier in the -file, which does a little bit of work for us: The first argument is an internal -identifier name, so that we can reference the page using `url_for` safely (if -the URL changes, so will the URLs that get generated by `url_for`). The second -argument is a path to the directory that contains the templates you'll make, but -with a preceding and trailing `/`. Follow the example of the other, currently -existing pages and add the appropriate `export_route` calls at the end. - -== Hacking the Templates - -The templates themselves live in the `sites` directory (under -`sites/getfedora.org/` still). There are already templates started (but not -currently exported in `main.py`) for `silverblue`, `coreos`, and `iot`, at time -of writing. - -[IMPORTANT] -==== -Every string you add *must* be enclosed in `{% trans %}` ... `{% endtrans %}` -blocks so that it can be translated. If the string spans multiple lines (we tend -to break at 80 characters but are fairly lenient about this), then the opening -block should instead be `{% trans trimmed %}` (the closing block is still just -`{% endtrans %}`). -==== - -You can copy the templates from the existing editions, if you need inspiration -or help. - -== Letting the Translators Do Their Thing - -Once the above is done, the next step is get all the strings in the hands of the -Fedora Translations team. If you have an account on Fedora's Zanata instance, -and are in the appropriate websites group on Zanata, and have a valid -`~/.config/zanata.ini` file, you can do this step yourself. Otherwise you'll -either need to be added to the appropriate team or have someone do this for you: - -Run `./scripts/translations-source.sh`. At the end of its output, it will give -you the Zanata command to push the strings up: `zanata push getfedora.org.pot` - -== Concluding - -Largely, that is it. You've added variables that are easy to update each release -(in `release.yaml`), you've exported the pages, written your templates in a -translatable way, and pushed those strings to the Translations team. Now you can -sit back and relax while the translators do their thing. Their translations will -go live immediately (well, within an hour) and automatically. diff --git a/docs/modules/ROOT/pages/newcontent-site.adoc b/docs/modules/ROOT/pages/newcontent-site.adoc deleted file mode 100644 index b468541..0000000 --- a/docs/modules/ROOT/pages/newcontent-site.adoc +++ /dev/null @@ -1,15 +0,0 @@ -= Creating A New Site -Rick Elrod -:page-authors: {author} - -In rare cases, you might need to create an entirely new site, rather than an -edition or page on getfedora.org. - -In a future world, this document will help you do so. - -For this to happen effectively, we'll need to abstract some things out from the -current getfedora.org work. - -But familiarizing yourself with link:https://flask.palletsprojects.com/[Flask] -and link:https://pythonhosted.org/Frozen-Flask/[Frozen-Flask] is a good starting -point, as we plan for all of our websites to build using this toolset. diff --git a/docs/modules/ROOT/pages/newcontent.adoc b/docs/modules/ROOT/pages/newcontent.adoc deleted file mode 100644 index b64ab51..0000000 --- a/docs/modules/ROOT/pages/newcontent.adoc +++ /dev/null @@ -1,23 +0,0 @@ -= Creating New Content -Rick Elrod -:page-authors: {author} - -Content can be broken into several different components, although some of the -process is the same for all cases. - -All new sites are being built with the Python link:http://flask.pocoo.org/[Flask] -framework and the link:https://pythonhosted.org/Frozen-Flask/[Frozen-Flask] library -for generating static pages. - -== New Editions - -New editions of Fedora should be added to the getfedora.org website. We are -trying to get away from having a bunch of `*.fedoraproject.org` sites for each -of the various editions (currently we have link:https://coreos.fedoraproject.org[], -link:https://iot.fedoraproject.org[], etc.). - -== New Websites - -There are cases, however, where the content being added is *not* a new edition, -and is deserving of having its own distinct website, separate from -getfedora.org. These cases should probably be somewhat rare. diff --git a/docs/modules/ROOT/pages/old--websites-release.adoc b/docs/modules/ROOT/pages/old--websites-release.adoc new file mode 100644 index 0000000..2bb52ee --- /dev/null +++ b/docs/modules/ROOT/pages/old--websites-release.adoc @@ -0,0 +1,314 @@ +== Webites Release SOP + +=== Preparing the website for a new release cycle + +* Obsolete GPG key ++ +One month after a Fedora release the release number 'FXX-2' (i.e. 1 +month after F21 release, F19 will be EOL) will be EOL (End of Life). At +this point we should drop the GPG key from the list in `+verify/+` and +move the keys to the obsolete keys page in keys/obsolete.html. +* Update GPG key ++ +After another couple of weeks and as the next release approaches, watch +the fedora-release package for a new key to be added. Use the +update-gpg-keys script in the fedora-web git repository to add it to +`+static/+`. Manually add it to `+/keys+` and `+/verify+` in all +websites where we use these keys: +** arm.fpo +** getfedora.org +** labs.fpo +** spins.fpo +* Steps +** Get a copy of the new key(s) from the fedora-release repo, you will +find FXX-primary and FXX-secondary keys. Save them in `+./tools+` to +make the update easier. https://pagure.io/fedora-repos +** Start by editing `+./tools/update-gpg-keys+` and adding the key-ids +of any obsolete keys to the obsolete_keys list. +** Then run that script to add the new key(s) to the fedora.gpg block: ++ +.... +fedora-web git:(master) cd tools/ +tools git:(master) ./update-gpg-keys RPM-GPG-KEY-fedora-23-primary +tools git:(master) ./update-gpg-keys RPM-GPG-KEY-fedora-23-secondary +.... ++ +This will add the key(s) to the keyblock in `+static/fedora.gpg+` and +create a text file for the key in `+static/$KEYID.txt+` as well. Verify +that these files have been created properly and contain all the keys +that they should. +** Handy checks: ++ +.... +gpg static/fedora.gpg + +or + +gpg static/$KEYID.txt +.... +** Adding `+--with-fingerprint+` option will add the fingerprint to the +output ++ +The output of fedora.gpg should contain only the actual keys, not the +obsolete keys. The single text files should contain the correct +information for the uploaded key. +** Next, add new key(s) to the list in `+data/verify.html+` and move the +new key informations in the keys page in +`+data/content/keys/index.html+`. A script to aid in generating the HTML +code for new keys is in `+./tools/make-gpg-key-html+`. It will print +HTML to stdout for each RPM-GPG-KEY-* file given as arguments. This is +suitable for copy/paste (or directly importing if your editor supports +this). Check the copied HTML code and select if the key info is for a +primary or secondary key (output says 'Primary or Secondary'). ++ +.... +tools git:(master) ./make-gpg-key-html RPM-GPG-KEY-fedora-23-primary +.... ++ +Build the website with `+make en test+` and carefully verify that the +data is correct. Please double check all keys in +`+http://localhost:5000/en/keys+` and +`+http://localhost:5000/en/verify+`. ++ +[NOTE] +.Note +==== +NOTE: the tool will give you an outdated output, adapt it to the new +websites and bootstrap layout! +==== + +=== Update website for Alpha release + +* Create the fXX-alpha branch from master ++ +.... +fedora-web git:(master) git push origin master:refs/heads/f23-alpha +.... ++ +and checkout to the new branch: ++ +.... +fedora-web git:(master) git checkout -t -b f23-alpha origin/f23-alpha +.... +* Update the global variables changing `+curr_state+` to Alpha for all +architectures. +* Add Alpha banner uploading it to +`+static/images/banners/f23alpha.png+` which should appear in every +`+${PRODUCT}/download/index.html+` page. Make sure the banner is shown +in all sidebars, also in labs, spins, and arm.fp.o. +* Check all Download links and paths in +`+${PRODUCT}/prerelease/index.html+` You can find all paths in bapp01 +(sudo su - mirrormanager first) or you can look at the downlaod page +`+http://dl.fedoraproject.org/pub/alt/stage+` +* Add CHECKSUM files to `+static/checksums+` and verify that the paths +are correct. The files should be in sundries01 and you can query them +with: ++ +.... +$ find /pub/fedora/linux/releases/test/23-Alpha/ -type f -name \ +*CHECKSUM* -exec cp '{}' . \; +.... ++ +Remember to add the right checksums to the right websites (same path). +* Add EC2 AMI IDs for Alpha. All IDs now are in the globalvar.py file. +We get all data from there, even the redirect path to trac the AMI IDs. +We now also have a script which is useful to get all the AMI IDs +uploaded with fedimg. Execute it to get the latest uploads, but don't +run the script too early, as new builds are added constantly. ++ +.... +fedora-web git:(fXX-alpha) python ~/fedora-web/tools/get_ami.py +.... +* Add CHECKSUM files also to `+http://spins.fedoraproject.org+` in +`+static/checksums+`. Verify the paths are correct in +`+data/content/verify.html+`. (see point e) to query them on +sundries01). Same for labs.fpo and arm.fpo. +* Verify all paths and links on http://spins.fpo, labs.fpo and arm.fpo. +* Update Alpha Image sizes and pre_cloud_composedate in +`+./build.d/globalvar.py+`. Verify they are right in Cloud images and +Docker image. +* Update the new POT files and push them to translation repository every +time you change text strings. +* Add this build to stg.fedoraproject.org (ansible syncStatic.sh.stg) to +test the pages online. +* Release Date: +** Merge the fXX-alpha branch to master and correct conflicts manually +** Remove the redirect of prerelease pages in ansible, edit: +`+ansible/playbooks/include/proxies-redirects.yml+`. Ask a sysadmin-main +to run the playbook. +** When ready and about 90 minutes before Release Time, push to master +** Tag the commit as new release and push it too: ++ +.... +$ git tag -a FXX-Alpha -m 'Releasing Fedora XX Alpha' +$ git push --tags +.... +** If needed follow link:#fire-in-the-hole[Fire in the Hole] + +=== Update website for Beta release + +* Create the fXX-alpha branch from master ++ +.... +fedora-web git:(master) git push origin master:refs/heads/f23-beta +.... ++ +and checkout to the new branch: ++ +.... +fedora-web git:(master) git checkout -t -b f23-beta origin/f23-beta +.... +* Update the global variables changing `+curr_state+` to Beta for all +architectures. +* Add Beta banner uploading it to `+static/images/banners/f23beta.png+` +which should appear in every `+${PRODUCT}/download/index.html+` page. +Make sure the banner is shown in all sidebars, also in labs, spins, and +arm.fp.o. +* Check all Download links and paths in +`+${PRODUCT}/prerelease/index.html+` You can find all paths in bapp01 +(sudo su - mirrormanager first) or you can look at the downlaod page +`+http://dl.fedoraproject.org/pub/alt/stage+` +* Add CHECKSUM files to `+static/checksums+` and verify that the paths +are correct. The files should be in sundries01 and you can query them +with: ++ +.... +$ find /pub/fedora/linux/releases/test/23-Beta/ -type f -name \ +*CHECKSUM* -exec cp '{}' . \; +.... ++ +Remember to add the right checksums to the right websites (same path). +* Add EC2 AMI IDs for Beta. All IDs now are in the globalvar.py file. We +get all data from there, even the redirect path to trac the AMI IDs. We +now also have a script which is useful to get all the AMI IDs uploaded +with fedimg. Execute it to get the latest uploads, but don't run the +script too early, as new builds are added constantly. ++ +.... +fedora-web git:(fXX-beta) python ~/fedora-web/tools/get_ami.py +.... +* Add CHECKSUM files also to `+http://spins.fedoraproject.org+` in +`+static/checksums+`. Verify the paths are correct in +`+data/content/verify.html+`. (see point e) to query them on +sundries01). Same for labs.fpo and arm.fpo. +* Remove static/checksums/Fedora-XX-Alpha* in all websites. +* Verify all paths and links on http://spins.fpo, labs.fpo and arm.fpo. +* Update Beta Image sizes and pre_cloud_composedate in +`+./build.d/globalvar.py+`. Verify they are right in Cloud images and +Docker image. +* Update the new POT files and push them to translation repository every +time you change text strings. +* Add this build to stg.fedoraproject.org (ansible syncStatic.sh.stg) to +test the pages online. +* Release Date: +** Merge the fXX-beta branch to master and correct conflicts manually +** When ready and about 90 minutes before Release Time, push to master +** Tag the commit as new release and push it too: ++ +.... +$ git tag -a FXX-Beta -m 'Releasing Fedora XX Beta' +$ git push --tags +.... +** If needed follow link:#fire-in-the-hole[Fire in the Hole] + +=== Update website for GA + +* Create the fXX branch from master ++ +.... +fedora-web git:(master) git push origin master:refs/heads/f23 +.... ++ +and checkout to the new branch: ++ +.... +fedora-web git:(master) git checkout -t -b f23 origin/f23 +.... +* Update the global variables changing `+curr_state+` to '' for all +architectures. +* Check all Download links and paths in +`+${PRODUCT}/download/index.html+` You can find all paths in bapp01 +(sudo su - mirrormanager first) or you can look at the downlaod page +`+http://dl.fedoraproject.org/pub/alt/stage+` +* Add CHECKSUM files to `+static/checksums+` and verify that the paths +are correct. The files should be in sundries01 and you can query them +with: ++ +.... +$ find /pub/fedora/linux/releases/23/ -type f -name \ +*CHECKSUM* -exec cp '{}' . \; +.... ++ +Remember to add the right checksums to the right websites (same path). +* At some point freeze translations. Add an empty PO_FREEZE file to +every website's directory you want to freeze. +* Add EC2 AMI IDs for GA. All IDs now are in the globalvar.py file. We +get all data from there, even the redirect path to trac the AMI IDs. We +now also have a script which is useful to get all the AMI IDs uploaded +with fedimg. Execute it to get the latest uploads, but don't run the +script too early, as new builds are added constantly. ++ +.... +fedora-web git:(fXX) python ~/fedora-web/tools/get_ami.py +.... +* Add CHECKSUM files also to `+http://spins.fedoraproject.org+` in +`+static/checksums+`. Verify the paths are correct in +`+data/content/verify.html+`. (see point e) to query them on +sundries01). Same for labs.fpo and arm.fpo. +* Remove static/checksums/Fedora-XX-Beta* in all websites. +* Verify all paths and links on http://spins.fpo, labs.fpo and arm.fpo. +* Update GA Image sizes and pre_cloud_composedate in +`+./build.d/globalvar.py+`. Verify they are right in Cloud images and +Docker image. +* Update static/js/checksum.js and check if the paths and checksum still +match. +* Update the new POT files and push them to translation repository every +time you change text strings. +* Add this build to stg.fedoraproject.org (ansible syncStatic.sh.stg) to +test the pages online. +* Release Date: +** Merge the fXX branch to master and correct conflicts manually +** Add the redirect of prerelease pages in ansible, edit +`+ansible/playbooks/include/proxies-redirects.yml+`. +** Ask a sysadmin-main to run playbook +** Unfreeze translations by deleting the PO_FREEZE files +** When ready and about 90 minutes before Release Time, push to master +** Update the short links for the Cloud Images for 'Fedora XX', 'Fedora +XX-1' and 'Latest' +** Tag the commit as new release and push it too: ++ +.... +$ git tag -a FXX -m 'Releasing Fedora XX' +$ git push --tags +.... +** If needed follow link:#fire-in-the-hole[Fire in the Hole] + +=== Fire in the hole + +We now use ansible for everything, and normally use a regular build to +make the websites live. If something is not happening as expected, you +should get in contact with a sysadmin-main to run the ansible playbook +again. + +All our puppet stuff, such as SyncStatic.sh and SyncTranslation.sh +scripts are now also in ansible! + +Staging server app02 and production server bapp01 do not exist anymore, +now our staging websites are on sundries01.stg and the production on +sundries01. Change your scripts accordingly and as sysadmin-web you +should have access to those servers as before. + +=== Tips + +* Merging branches ++ +This can be useful if you're _sure_ all new changes on devel branch +should go into the master branch. Conflicts will be solved directly +accepting only the changes in the devel branch. If you're not 100% sure +do a normal merge and fix conflicts manually! ++ +.... +$ git merge f23-beta +$ git checkout --theirs f23-beta [list of conflicting po files] +$ git commit +.... diff --git a/docs/modules/ROOT/pages/setup-docker.adoc b/docs/modules/ROOT/pages/setup-docker.adoc deleted file mode 100644 index 4f927ef..0000000 --- a/docs/modules/ROOT/pages/setup-docker.adoc +++ /dev/null @@ -1,76 +0,0 @@ -= Getting Set Up (using Docker) -Rick Elrod -:page-authors: {author} - -== Preliminary Notes - -It is now easier to get started on developing the Fedora Websites with the use -of Docker (or Podman). - -We ship a `Dockerfile` which will install dependencies into an image -for you, so all you are left to do is mount the site as a volume, pull -translations, and start the development server. - -[NOTE] -==== -The documentation here refers to `docker`, but our fairly simple use -of it means that things are likely to work with `podman` with little -modification. -==== - -== Building the container image - -First clone the repository: - -[source,bash] ----- -git clone https://pagure.io/fedora-web/websites.git ----- - -(You may instead clone your fork of it, or add your fork as a second -remote later on.) - -Now ensure Docker is running and run: - -[source,bash] ----- -sudo docker build -t fedora-websites . ----- - -This will generate a container image for you to use. - -== Pulling translations - -We have a script for pulling translations. Let's call it from within -the container: - -[source,bash] ----- -sudo docker run -it --rm -v "$(pwd):/opt/:z" fedora-websites ./scripts/pull-translations.sh ----- - - -Notice here that we are mounting a volume (`-v`) in Docker which -points to our check-out of the repository. We're referring to the -`fedora-websites` image created above, and calling the -`./scripts/pull-translations.sh` script from within it. - -== Running the development server - -Now we are ready to run the development server: - -[source,bash] ----- -sudo docker run -it --rm -v "$(pwd):/opt/:z" -p 5000:5000 fedora-websites flask run --reload --host 0.0.0.0 ----- - -Note that we need `-p 5000:5000` so that we can access the development -server from our actual host. Also notice that we need to tell Flask to -listen on `0.0.0.0` as by default it listens on `127.0.0.1` which -won't be accessible outside of the container. - -You may now go to `http://localhost:5000/` in your browser of choice. - -Now you are ready to go and any changes you make in the repository -should be reflected immediately upon refreshing the page in your -browser. diff --git a/docs/modules/ROOT/pages/setup.adoc b/docs/modules/ROOT/pages/setup.adoc deleted file mode 100644 index e715bf2..0000000 --- a/docs/modules/ROOT/pages/setup.adoc +++ /dev/null @@ -1,103 +0,0 @@ -= Getting Set Up -Rick Elrod -:page-authors: {author} - -[NOTE] -==== -We now have documentation on using the `Dockerfile` which ships in the Fedora -websites repository, and suggest trying that method before using the method -outlined on this page. See link:../setup-docker[this tutorial]. -==== - -== Preliminary Notes - -There are some open tickets (https://pagure.io/fedora-web/websites/issue/31[31], -https://pagure.io/fedora-web/websites/issue/11[11]) about getting the websites -repository building on Fedora with Python 3. - -However, it should be able to be built on Fedora 30, using Python 2 packages, -for now. - -=== Fedora 29 Alternative - -Note, the dependencies below may not currently resolve due to package renaming -in Fedora 30. If the dependencies do not resolve in Fedora 30, running Flask -from a Fedora 29 container is an alternative. An example to run the Fedora 29 -container using `podman` is as follows: - -``` -# Expose the default port for Flask, 5000. -podman run --expose 5000 --net=host --privileged -v /path/to/websites/repo:/path/to/websites/repo -ti registry.fedoraproject.org/fedora:29 -``` - -== Dependencies - -That said, assuming Fedora 30, install the dependencies as follows -footnote:[This list comes directly from the Fedora Infrastructure OpenShift -build for Websites found -https://infrastructure.fedoraproject.org/cgit/ansible.git/tree/roles/openshift-apps/websites/templates/buildconfig.yml[here].]: - -[source,bash] ----- -dnf install \ - git \ - python-flask \ - python-frozen-flask \ - python-flask-assets \ - python-rjsmin \ - python-cssmin \ - python-flask-babel \ - python-flask-htmlmin \ - python-cssutils \ - rubygem-sass \ - babel \ - python3-jinja2 \ - python-pyyaml \ - python-dateutil \ - python-dogpile-cache \ - python-requests \ - python-zanata-client ----- - -== Pull Strings - -Now we need to pull the current translations. After installing the dependencies -above, you can `cd` into `sites/getfedora.org/` and run: -`./scripts/pull-translations.sh`. - -Once the dependencies are installed and translations are pulled, you can do one -of two things: - -== Use the Development Server - -One option is to use the Flask built-in development server. This is handy -because it prevents you from needing to build the websites every time you change -something. However, it bypasses the Frozen-Flask system which creates are static -sites, entirely, so it's not entirely an accurate representation of what goes -live. - -To use the development server: - -[source,bash] ----- -export FLASK_APP=main.py -flask run --reload ----- - -Now you many visit http://localhost:5000/ to get to the site. - -== Use Apache - -Alternatively, you may simply run `python main.py`. You'll get a statically -built site in the `./build/` directory. However, the HTML files are all -language-code-suffixed as Apache/httpd MultiViews system expects -(e.g. `index.html.en`). As a result you *cannot* just run a simple HTTP server -(like `python -m SimpleHTTPServer`) in the `./build/` directory, unfortunately. - -You can, however, set up an Apache on your system, and point it to the -`./build/` directory. - -[NOTE] -==== -(We should probably add an example Apache config here at some point). -==== diff --git a/docs/modules/ROOT/pages/translation-flow.adoc b/docs/modules/ROOT/pages/translation-flow.adoc index c017809..adeb1b3 100644 --- a/docs/modules/ROOT/pages/translation-flow.adoc +++ b/docs/modules/ROOT/pages/translation-flow.adoc @@ -1,5 +1,5 @@ = Translation flow (for Fedora websites) - Jan Kuparinen +Jan Kuparinen :page-authors: {author} == General @@ -19,7 +19,7 @@ Generally every text inside web page should be surrounded with tags: == Generating pot file First we need to pull all translatable strings into a file called getfedora.org.pot -This file is generated by running: +This file is generated by running: [source,bash] ---- @@ -48,7 +48,7 @@ Update strings to the language files podman run -it --rm -v "$(pwd):/opt/:z" fedora-websites ./scripts/translations-update-local.sh ---- -Now edit desired language file, for example +Now edit desired language file, for example [source,bash] ---- @@ -58,7 +58,7 @@ Find the string you want to test, format inside file is: `#: partials/templates/download_card.html:13` Location(s) of string. `msgid "Download"` Text in english. - `msgstr "Lataa"` Text in desired language. + `msgstr "Lataa"` Text in desired language. Edit the `msgstr` diff --git a/docs/modules/ROOT/partials/attributes.adoc b/docs/modules/ROOT/partials/attributes.adoc new file mode 100644 index 0000000..2015c83 --- /dev/null +++ b/docs/modules/ROOT/partials/attributes.adoc @@ -0,0 +1,12 @@ +:comms-discourse: https://discussion.fedoraproject.org/c/project/websites/66 +:comms-irc: #fedora-websites +:comms-irc-server: irc.libera.chat +:comms-irc-server-port: 6697 +:comms-listserv: https://lists.fedoraproject.org/archives/list/websites@lists.fedoraproject.org/ +:comms-matrix: https://matrix.to/#/#fedora-websites:matrix.org +:comms-telegram: https://t.me/joinchat/hWQIgi7L79k3Nzk5 +:comms-video: https://meet.jit.si/fedora-websites-apps-meeting +:comms-video-name: Jisti Meet +:meeting-day: Tuesday +:meeting-time: 15:00 - 16:00 UTC +:year: 2021 diff --git a/docs/modules/dev/nav.adoc b/docs/modules/dev/nav.adoc new file mode 100644 index 0000000..9ae8c1d --- /dev/null +++ b/docs/modules/dev/nav.adoc @@ -0,0 +1,3 @@ +* xref:index.adoc[*Development*] +** xref:setup-containers.adoc[Set up your environment (using containers)] +** xref:setup.adoc[Set up your environment (old method)] diff --git a/docs/modules/dev/pages/index.adoc b/docs/modules/dev/pages/index.adoc new file mode 100644 index 0000000..dacc707 --- /dev/null +++ b/docs/modules/dev/pages/index.adoc @@ -0,0 +1,7 @@ += Developer documentation +Websites & Apps Team; Justin W. Flory +:page-authors: {author}, {author_2} + +This section of the W&A Team documentation is focused for developers and on day-to-day development. +The purpose of this documentation is to gather the various documentation sources on different websites and collect them here. +This is like an index of Fedora's website documentation. diff --git a/docs/modules/dev/pages/setup-containers.adoc b/docs/modules/dev/pages/setup-containers.adoc new file mode 100644 index 0000000..f420a04 --- /dev/null +++ b/docs/modules/dev/pages/setup-containers.adoc @@ -0,0 +1,68 @@ += Set up your environment (using containers) +Rick Elrod; Justin W. Flory +:page-authors: {author}, {author_2} +:page-aliases: websites::setup-docker.adoc + + +== Preliminary Notes + +It is now easier to get started on developing the Fedora Websites with the use of Docker (or Podman). + +We ship a `Dockerfile` which will install dependencies into an image for you, so all you are left to do is mount the site as a volume, pull translations, and start the development server. + +[NOTE] +==== +The documentation here refers to `docker`, but our fairly simple use of it means that things are likely to work with `podman` with little modification. +==== + + +== Building the container image + +First clone the repository: + +[source,bash] +---- +git clone https://pagure.io/fedora-web/websites.git +---- + +(You may instead clone your fork of it, or add your fork as a second remote later on.) + +Now ensure Docker is running and run: + +[source,bash] +---- +sudo docker build -t fedora-websites . +---- + +This will generate a container image for you to use. + + +== Pulling translations + +We have a script for pulling translations. +Let's call it from within the container: + +[source,bash] +---- +sudo docker run -it --rm -v "$(pwd):/opt/:z" fedora-websites ./scripts/pull-translations.sh +---- + +Notice here that we are mounting a volume (`-v`) in Docker which points to our check-out of the repository. +We're referring to the `fedora-websites` image created above, and calling the `./scripts/pull-translations.sh` script from within it. + + +== Running the development server + +Now we are ready to run the development server: + +[source,bash] +---- +sudo docker run -it --rm -v "$(pwd):/opt/:z" -p 5000:5000 fedora-websites flask run --reload --host 0.0.0.0 +---- + +Note that we need `-p 5000:5000` so that we can access the development server from our actual host. +Also notice that we need to tell Flask to listen on `0.0.0.0` as by default it listens on `127.0.0.1` which won't be accessible outside of the container. + +You may now go to `http://localhost:5000/` in your browser of choice. + +Now you are ready to go and any changes you make in the repository should be reflected immediately upon refreshing the page in your browser. diff --git a/docs/modules/dev/pages/setup.adoc b/docs/modules/dev/pages/setup.adoc new file mode 100644 index 0000000..3f21132 --- /dev/null +++ b/docs/modules/dev/pages/setup.adoc @@ -0,0 +1,97 @@ += Set up your environment (old way) +Rick Elrod; Justin W. Flory +:page-authors: {author}, {author_2} +:page-aliases: websites::setup.adoc + +[NOTE] +==== +We now have documentation on using the `Dockerfile` which ships in the Fedora websites repository. +We and trying that method before using the method outlined on this page. +See xref:setup-containers.adoc[this tutorial]. +==== + +== Preliminary Notes + +There are some open tickets (https://pagure.io/fedora-web/websites/issue/31[31], https://pagure.io/fedora-web/websites/issue/11[11]) about getting the websites repository building on Fedora with Python 3. + +However, it should be able to be built on Fedora 30, using Python 2 packages, for now. + +=== Fedora 29 Alternative + +Note, the dependencies below may not currently resolve due to package renaming in Fedora 30. +If the dependencies do not resolve in Fedora 30, running Flask from a Fedora 29 container is an alternative. +An example to run the Fedora 29 container using `podman` is as follows: + +[source,bash] +---- +# Expose the default port for Flask, 5000. +podman run --expose 5000 --net=host --privileged -v /path/to/websites/repo:/path/to/websites/repo -ti registry.fedoraproject.org/fedora:29 +---- + + +== Dependencies + +That said, assuming Fedora 30, install the following dependencies. +Note this list comes directly from the Fedora Infrastructure OpenShift build for Websites found link:https://infrastructure.fedoraproject.org/cgit/ansible.git/tree/roles/openshift-apps/websites/templates/buildconfig.yml[here]: + +[source,bash] +---- +dnf install \ + git \ + python-flask \ + python-frozen-flask \ + python-flask-assets \ + python-rjsmin \ + python-cssmin \ + python-flask-babel \ + python-flask-htmlmin \ + python-cssutils \ + rubygem-sass \ + babel \ + python3-jinja2 \ + python-pyyaml \ + python-dateutil \ + python-dogpile-cache \ + python-requests \ + python-zanata-client +---- + + +== Pull Strings + +Now we need to pull the current translations. +After installing the dependencies above, you can `cd` into `sites/getfedora.org/` and run: +`./scripts/pull-translations.sh`. + +Once the dependencies are installed and translations are pulled, you can do one of two things: + + +== Use the Development Server + +One option is to use the Flask built-in development server. +This is handy because it prevents you from needing to build the websites every time you change something. +However, it bypasses the Frozen-Flask system which creates are static sites, entirely, so it's not entirely an accurate representation of what goes live. + +To use the development server: + +[source,bash] +---- +export FLASK_APP=main.py +flask run --reload +---- + +Now you many visit http://localhost:5000/ to get to the site. + +== Use Apache + +Alternatively, you may simply run `python main.py`. +You'll get a statically built site in the `./build/` directory. +However, the HTML files are all language-code-suffixed as Apache/httpd MultiViews system expects (e.g. `index.html.en`). +As a result you *cannot* just run a simple HTTP server (like `python -m SimpleHTTPServer`) in the `./build/` directory, unfortunately. + +You can, however, set up an Apache on your system, and point it to the `./build/` directory. + +[NOTE] +==== +We should probably add an example Apache config here at some point. +==== diff --git a/docs/modules/runbook/nav.adoc b/docs/modules/runbook/nav.adoc new file mode 100644 index 0000000..aeb4473 --- /dev/null +++ b/docs/modules/runbook/nav.adoc @@ -0,0 +1,5 @@ +* xref:index.adoc[*Runbook*] +** xref:newcontent.adoc[Creating New Content] +*** xref:newcontent-edition.adoc[New Edition] +*** xref:newcontent-site.adoc[New Site] +** xref:meetings.adoc[Meetings] diff --git a/docs/modules/runbook/pages/index.adoc b/docs/modules/runbook/pages/index.adoc new file mode 100644 index 0000000..0e866e2 --- /dev/null +++ b/docs/modules/runbook/pages/index.adoc @@ -0,0 +1,16 @@ += Websites & Apps Runbook +Websites & Apps Team; Justin W. Flory +:page-authors: {author}, {author_2} + +This Runbook documents information about the Fedora Website and Apps team and our core operations. +It is a living collection of documents that explain the governance and organization of our team. +The Runbook is a reference for current and future members of the community to learn about the inner-workings of what we do. + +[[who]] +== Who is the Runbook for? + +The Runbook is a resource for anyone who wishes to participate in Fedora's Websites & Apps community. +Anyone is welcome to review the Runbook and make suggestions. + +The Runbook is officially maintained by Websites & Apps Team leads. +However, all members of the community are welcome and encouraged to keep their processes or areas of knowledge regularly updated. diff --git a/docs/modules/runbook/pages/meetings.adoc b/docs/modules/runbook/pages/meetings.adoc new file mode 100644 index 0000000..44ba609 --- /dev/null +++ b/docs/modules/runbook/pages/meetings.adoc @@ -0,0 +1,35 @@ +include::ROOT:partial$attributes.adoc[] + += Meetings +Justin W. Flory +:page-authors: {author} + +The Websites & Apps Team meets weekly: + +* Location: + link:++{COMMS-VIDEO}++[*{COMMS-VIDEO-NAME} room*] +* Day: + *{MEETING-DAY}s* +* Time: + *{MEETING-TIME}* + + +[[activities]] +== Activities + +Our weekly meeting includes these topics: + +* Review tickets and pull requests +* Discuss on team direction +* Check in with each other +* Plan activities + +Feel free to attend a meeting and ask any questions you have. +If you want to flag a topic for discussion or to be addressed by the group, message a team lead in advance so we can plan a slot in our agenda. + + +[[resources]] +== Resources + +Links, notes, and shared content for our meetings. +To be updated soon. diff --git a/docs/modules/runbook/pages/newcontent-edition.adoc b/docs/modules/runbook/pages/newcontent-edition.adoc new file mode 100644 index 0000000..0ce0554 --- /dev/null +++ b/docs/modules/runbook/pages/newcontent-edition.adoc @@ -0,0 +1,90 @@ += New Edition +Rick Elrod; Justin W. Flory +:page-authors: {author}, {author_2} +:page-aliases: websites::newcontent-edition.adoc + +== Introduction + +Fedora editions are "versions" of Fedora that users can install. These include +"official" editions (Workstation and Server at time of writing), but the +ultimate goal in Websites is to also make Spins and Labs editions be considered +"editions" in some form as far as websites are concerned. That is to say, we'd +like to ultimately have Spins and Labs have a section on the main getfedora.org +site, rendering link:https://spins.fedorparoject.org/[] and +link:https://labs.fedoraproject.org/[] useless and able to be gotten rid of. +Doing this effectively will take some time. + +Also note that most of the content in this document applies to adding pages in +general, with the notable exception of the `release.yaml` edits. Adding a page +to getfedora.org should follow largely the same process, though. + +[NOTE] +==== +All new editions should be added to getfedora.org, to aid in our goal of getting +rid of all of the `*.fedoraproject.org` edition-specific subdomain sites. This +generates a more consistent and less confusing user experience and makes +maintenance of the websites easier going forward. Everything in this document +assumes that you are working with the getfedora.org codebase, and NOT creating a +new site from scratch. +==== + +Now then, all work in this document takes place in the repository in which +link:https://pagure.io/fedora-web/websites/[getfedora.org] lives, and particularly +in the `sites/getfedora.org/` directory. + +== Edition-specific Release Variables + +The first step is to edit `release.yaml`, and add the relevant sections under +`ga` and `beta` for your new edition. Use `workstation` and `server` as +templates. You might not need all variables that these existing sections have, +or you might need to add new ones, depending on your templates, but these blocks +should get you started. + +== Exporting the Edition Routes + +Now, open `main.py` and go to near the bottom, where you'll note a number of +`export_route(...)` calls. This method is a custom method defined earlier in the +file, which does a little bit of work for us: The first argument is an internal +identifier name, so that we can reference the page using `url_for` safely (if +the URL changes, so will the URLs that get generated by `url_for`). The second +argument is a path to the directory that contains the templates you'll make, but +with a preceding and trailing `/`. Follow the example of the other, currently +existing pages and add the appropriate `export_route` calls at the end. + +== Hacking the Templates + +The templates themselves live in the `sites` directory (under +`sites/getfedora.org/` still). There are already templates started (but not +currently exported in `main.py`) for `silverblue`, `coreos`, and `iot`, at time +of writing. + +[IMPORTANT] +==== +Every string you add *must* be enclosed in `{% trans %}` ... `{% endtrans %}` +blocks so that it can be translated. If the string spans multiple lines (we tend +to break at 80 characters but are fairly lenient about this), then the opening +block should instead be `{% trans trimmed %}` (the closing block is still just +`{% endtrans %}`). +==== + +You can copy the templates from the existing editions, if you need inspiration +or help. + +== Letting the Translators Do Their Thing + +Once the above is done, the next step is get all the strings in the hands of the +Fedora Translations team. If you have an account on Fedora's Zanata instance, +and are in the appropriate websites group on Zanata, and have a valid +`~/.config/zanata.ini` file, you can do this step yourself. Otherwise you'll +either need to be added to the appropriate team or have someone do this for you: + +Run `./scripts/translations-source.sh`. At the end of its output, it will give +you the Zanata command to push the strings up: `zanata push getfedora.org.pot` + +== Concluding + +Largely, that is it. You've added variables that are easy to update each release +(in `release.yaml`), you've exported the pages, written your templates in a +translatable way, and pushed those strings to the Translations team. Now you can +sit back and relax while the translators do their thing. Their translations will +go live immediately (well, within an hour) and automatically. diff --git a/docs/modules/runbook/pages/newcontent-site.adoc b/docs/modules/runbook/pages/newcontent-site.adoc new file mode 100644 index 0000000..f00d396 --- /dev/null +++ b/docs/modules/runbook/pages/newcontent-site.adoc @@ -0,0 +1,16 @@ += Creating A New Site +Rick Elrod; Justin W. Flory +:page-authors: {author}, {author_2} +:page-aliases: websites::newcontent-site.adoc + +In rare cases, you might need to create an entirely new site, rather than an +edition or page on getfedora.org. + +In a future world, this document will help you do so. + +For this to happen effectively, we'll need to abstract some things out from the +current getfedora.org work. + +But familiarizing yourself with link:https://flask.palletsprojects.com/[Flask] +and link:https://pythonhosted.org/Frozen-Flask/[Frozen-Flask] is a good starting +point, as we plan for all of our websites to build using this toolset. diff --git a/docs/modules/runbook/pages/newcontent.adoc b/docs/modules/runbook/pages/newcontent.adoc new file mode 100644 index 0000000..08caded --- /dev/null +++ b/docs/modules/runbook/pages/newcontent.adoc @@ -0,0 +1,24 @@ += Creating New Content +Rick Elrod; Justin W. Flory +:page-authors: {author}, {author_2} +:page-aliases: websites::newcontent.adoc + +Content can be broken into several different components, although some of the +process is the same for all cases. + +All new sites are being built with the Python link:http://flask.pocoo.org/[Flask] +framework and the link:https://pythonhosted.org/Frozen-Flask/[Frozen-Flask] library +for generating static pages. + +== New Editions + +New editions of Fedora should be added to the getfedora.org website. We are +trying to get away from having a bunch of `*.fedoraproject.org` sites for each +of the various editions (currently we have link:https://coreos.fedoraproject.org[], +link:https://iot.fedoraproject.org[], etc.). + +== New Websites + +There are cases, however, where the content being added is *not* a new edition, +and is deserving of having its own distinct website, separate from +getfedora.org. These cases should probably be somewhat rare. diff --git a/docs/nginx.conf b/docs/nginx.conf deleted file mode 100644 index f7093b3..0000000 --- a/docs/nginx.conf +++ /dev/null @@ -1,14 +0,0 @@ -server { - listen 80; - server_name localhost; - - location / { - root /antora/public; - index index.html index.htm; - } - - error_page 500 502 503 504 /50x.html; - location = /50x.html { - root /usr/share/nginx/html; - } -} diff --git a/docs/preview.sh b/docs/preview.sh deleted file mode 100755 index 4270107..0000000 --- a/docs/preview.sh +++ /dev/null @@ -1,18 +0,0 @@ -#!/bin/sh - -if [ "$(uname)" = "Darwin" ]; then - # Running on macOS. - # Let's assume that the user has the Docker CE installed - # which doesn't require a root password. - echo "The preview will be available at http://localhost:8080/" - docker run --rm -v "$(pwd):/antora:ro" -v "$(pwd)/nginx.conf:/etc/nginx/conf.d/default.conf:ro" -p 8080:80 nginx - -elif [ "$(expr substr "$(uname -s)" 1 5)" = "Linux" ]; then - # Running on Linux. - # Fedora Workstation has python3 installed as a default, so using that - echo "" - echo "The preview is available at http://localhost:8080" - echo "" - cd ./public - python3 -m http.server 8080 -fi diff --git a/docs/site.yml b/docs/site.yml deleted file mode 100644 index b8fdc7f..0000000 --- a/docs/site.yml +++ /dev/null @@ -1,20 +0,0 @@ -site: - title: Fedora Websites - start_page: websites::index -content: - sources: - - url: . - branches: HEAD -ui: - bundle: - url: https://asamalik.fedorapeople.org/ui-bundle.zip - snapshot: true - default_layout: with_menu -output: - clean: true - dir: ./public - destinations: - - provider: archive -runtime: - pull: true - cache_dir: ./cache diff --git a/nginx.conf b/nginx.conf new file mode 100644 index 0000000..f7093b3 --- /dev/null +++ b/nginx.conf @@ -0,0 +1,14 @@ +server { + listen 80; + server_name localhost; + + location / { + root /antora/public; + index index.html index.htm; + } + + error_page 500 502 503 504 /50x.html; + location = /50x.html { + root /usr/share/nginx/html; + } +} diff --git a/old_docs/Makefile b/old_docs/Makefile deleted file mode 100644 index 9eea7a5..0000000 --- a/old_docs/Makefile +++ /dev/null @@ -1,177 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build - -# User-friendly check for sphinx-build -ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1) -$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/) -endif - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext - -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " dirhtml to make HTML files named index.html in directories" - @echo " singlehtml to make a single large HTML file" - @echo " pickle to make pickle files" - @echo " json to make JSON files" - @echo " htmlhelp to make HTML files and a HTML help project" - @echo " qthelp to make HTML files and a qthelp project" - @echo " devhelp to make HTML files and a Devhelp project" - @echo " epub to make an epub" - @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" - @echo " latexpdf to make LaTeX files and run them through pdflatex" - @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" - @echo " text to make text files" - @echo " man to make manual pages" - @echo " texinfo to make Texinfo files" - @echo " info to make Texinfo files and run them through makeinfo" - @echo " gettext to make PO message catalogs" - @echo " changes to make an overview of all changed/added/deprecated items" - @echo " xml to make Docutils-native XML files" - @echo " pseudoxml to make pseudoxml-XML files for display purposes" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - -clean: - rm -rf $(BUILDDIR)/* - -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -dirhtml: - $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." - -singlehtml: - $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml - @echo - @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." - -pickle: - $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle - @echo - @echo "Build finished; now you can process the pickle files." - -json: - $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json - @echo - @echo "Build finished; now you can process the JSON files." - -htmlhelp: - $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp - @echo - @echo "Build finished; now you can run HTML Help Workshop with the" \ - ".hhp project file in $(BUILDDIR)/htmlhelp." - -qthelp: - $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp - @echo - @echo "Build finished; now you can run "qcollectiongenerator" with the" \ - ".qhcp project file in $(BUILDDIR)/qthelp, like this:" - @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/FedoraWebsites.qhcp" - @echo "To view the help file:" - @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/FedoraWebsites.qhc" - -devhelp: - $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp - @echo - @echo "Build finished." - @echo "To view the help file:" - @echo "# mkdir -p $$HOME/.local/share/devhelp/FedoraWebsites" - @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/FedoraWebsites" - @echo "# devhelp" - -epub: - $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub - @echo - @echo "Build finished. The epub file is in $(BUILDDIR)/epub." - -latex: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo - @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." - @echo "Run \`make' in that directory to run these through (pdf)latex" \ - "(use \`make latexpdf' here to do that automatically)." - -latexpdf: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through pdflatex..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -latexpdfja: - $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex - @echo "Running LaTeX files through platex and dvipdfmx..." - $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja - @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." - -text: - $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text - @echo - @echo "Build finished. The text files are in $(BUILDDIR)/text." - -man: - $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man - @echo - @echo "Build finished. The manual pages are in $(BUILDDIR)/man." - -texinfo: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo - @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." - @echo "Run \`make' in that directory to run these through makeinfo" \ - "(use \`make info' here to do that automatically)." - -info: - $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo - @echo "Running Texinfo files through makeinfo..." - make -C $(BUILDDIR)/texinfo info - @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." - -gettext: - $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale - @echo - @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." - -changes: - $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes - @echo - @echo "The overview file is in $(BUILDDIR)/changes." - -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -xml: - $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml - @echo - @echo "Build finished. The XML files are in $(BUILDDIR)/xml." - -pseudoxml: - $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml - @echo - @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." diff --git a/old_docs/source/index.rst b/old_docs/source/index.rst deleted file mode 100644 index be44b45..0000000 --- a/old_docs/source/index.rst +++ /dev/null @@ -1,59 +0,0 @@ -.. Fedora Websites documentation master file, created by - sphinx-quickstart on Mon Feb 22 09:57:22 2016. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -=============== -Fedora Websites -=============== - -Contents: - -.. toctree:: - :maxdepth: 2 - - websites_release - -This page contains information about the Fedora Websites team. - -.. _websites-contact-info: - -Contact Information -=================== - -* IRC: ``#fedora-websites`` on irc.libera.chat -* Mailing List: `websites@lists.fedoraproject.org `_ -* Issue tracker: `Fedora Websites Trac Tickets `_ - -What does the Websites team do -============================== - -The Fedora Websites initiative aims to improve Fedora's image and to create the best possible interface for users and contributors on the Internet. The key goals of this effort include: - -* Consolidating all key Fedora websites onto one uniform scheme -* Maintaining content that doesn't fall under any particular sub-project -* Generally, making the sites as fun and exciting as the project they represent - -In order to better achieve these goals, as well as to benefit the community, the work of this project will involve third-party site maintainers where possible. The direct work of this project is limited to the formal `Get Fedora website `_. - -Work on specific sections of the sites will be coordinated by the appropriate projects. A great deal of coordination will be necessary with the `Fedora Infrastructure Team `_ , `Fedora Documentation Project `_ and the `Fedora Marketing Project `_. - -Joining the Websites team -========================= - -If you're interested in helping the Websites team, please refer to our `Join page `_. -Most discussions about websites happen in ``#fedora-websites``, so just pass by and say hello. - -Bugfixing -========= - -If you found a bug in the websites want to fix it by yourself, read the `instructions how to fix bugs on the Fedora websites `_. Otherwise please report them in the `Websites trac `_. - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - diff --git a/old_docs/source/websites_release.rst b/old_docs/source/websites_release.rst deleted file mode 100644 index a4b00f8..0000000 --- a/old_docs/source/websites_release.rst +++ /dev/null @@ -1,354 +0,0 @@ - -=================== -Webites Release SOP -=================== - -Preparing the website for a new release cycle -============================================= - -* Obsolete GPG key - - One month after a Fedora release the release number 'FXX-2' (i.e. 1 month - after F21 release, F19 will be EOL) will be EOL (End of Life). - At this point we should drop the GPG key from the list in ``verify/`` and move - the keys to the obsolete keys page in keys/obsolete.html. - -* Update GPG key - - After another couple of weeks and as the next release approaches, watch - the fedora-release package for a new key to be added. Use the update-gpg-keys - script in the fedora-web git repository to add it to ``static/``. Manually add it - to ``/keys`` and ``/verify`` in all websites where we use these keys: - - * arm.fpo - * getfedora.org - * labs.fpo - * spins.fpo - - -* Steps - - * Get a copy of the new key(s) from the fedora-release repo, you will - find FXX-primary and FXX-secondary keys. Save them in ``./tools`` to make the - update easier. - https://pagure.io/fedora-repos - - * Start by editing ``./tools/update-gpg-keys`` and adding the key-ids of - any obsolete keys to the obsolete_keys list. - - * Then run that script to add the new key(s) to the fedora.gpg block: - - :: - - fedora-web git:(master) cd tools/ - tools git:(master) ./update-gpg-keys RPM-GPG-KEY-fedora-23-primary - tools git:(master) ./update-gpg-keys RPM-GPG-KEY-fedora-23-secondary - - This will add the key(s) to the keyblock in ``static/fedora.gpg`` and - create a text file for the key in ``static/$KEYID.txt`` as well. Verify - that these files have been created properly and contain all the keys - that they should. - - * Handy checks: - - :: - - gpg static/fedora.gpg - - or - - gpg static/$KEYID.txt - - * Adding ``--with-fingerprint`` option will add the fingerprint to the - output - - The output of fedora.gpg should contain only the actual keys, not the - obsolete keys. - The single text files should contain the correct information for the - uploaded key. - - * Next, add new key(s) to the list in ``data/verify.html`` and move the new - key informations in the keys page in ``data/content/keys/index.html``. A - script to aid in generating the HTML code for new keys is in - ``./tools/make-gpg-key-html``. - It will print HTML to stdout for each RPM-GPG-KEY-* file given as - arguments. This is suitable for copy/paste (or directly importing if - your editor supports this). - Check the copied HTML code and select if the key info is for a primary - or secondary key (output says 'Primary or Secondary'). - - :: - - tools git:(master) ./make-gpg-key-html RPM-GPG-KEY-fedora-23-primary - - Build the website with ``make en test`` and carefully verify that the - data is correct. Please double check all keys in ``http://localhost:5000/en/keys`` - and ``http://localhost:5000/en/verify``. - - .. note:: - - NOTE: the tool will give you an outdated output, adapt it to the new - websites and bootstrap layout! - - -Update website for Alpha release -================================ - -* Create the fXX-alpha branch from master - - :: - - fedora-web git:(master) git push origin master:refs/heads/f23-alpha - - and checkout to the new branch: - - :: - - fedora-web git:(master) git checkout -t -b f23-alpha origin/f23-alpha - -* Update the global variables changing ``curr_state`` to Alpha for all architectures. - -* Add Alpha banner uploading it to ``static/images/banners/f23alpha.png`` - which should appear in every ``${PRODUCT}/download/index.html`` page. - Make sure the banner is shown in all sidebars, also in labs, spins, and arm.fp.o. - -* Check all Download links and paths in ``${PRODUCT}/prerelease/index.html`` - You can find all paths in bapp01 (sudo su - mirrormanager first) or - you can look at the downlaod page ``http://dl.fedoraproject.org/pub/alt/stage`` - -* Add CHECKSUM files to ``static/checksums`` and verify that the paths are - correct. The files should be in sundries01 and you can query them with: - - :: - - $ find /pub/fedora/linux/releases/test/23-Alpha/ -type f -name \ - *CHECKSUM* -exec cp '{}' . \; - - Remember to add the right checksums to the right websites (same path). - -* Add EC2 AMI IDs for Alpha. All IDs now are in the globalvar.py file. - We get all data from there, even the redirect path to trac the AMI IDs. - We now also have a script which is useful to get all the AMI IDs uploaded - with fedimg. Execute it to get the latest uploads, but don't run the script too - early, as new builds are added constantly. - - :: - - fedora-web git:(fXX-alpha) python ~/fedora-web/tools/get_ami.py - -* Add CHECKSUM files also to ``http://spins.fedoraproject.org`` in - ``static/checksums``. Verify the paths are correct in ``data/content/verify.html``. - (see point e) to query them on sundries01). Same for labs.fpo and arm.fpo. - -* Verify all paths and links on http://spins.fpo, labs.fpo and arm.fpo. - -* Update Alpha Image sizes and pre_cloud_composedate in ``./build.d/globalvar.py``. - Verify they are right in Cloud images and Docker image. - -* Update the new POT files and push them to translation repository every time - you change text strings. - -* Add this build to stg.fedoraproject.org (ansible syncStatic.sh.stg) to - test the pages online. - -* Release Date: - - * Merge the fXX-alpha branch to master and correct conflicts manually - * Remove the redirect of prerelease pages in ansible, edit: ``ansible/playbooks/include/proxies-redirects.yml``. Ask a sysadmin-main to run the playbook. - * When ready and about 90 minutes before Release Time, push to master - * Tag the commit as new release and push it too: - - :: - - $ git tag -a FXX-Alpha -m 'Releasing Fedora XX Alpha' - $ git push --tags - - * If needed follow `Fire in the Hole <#fire-in-the-hole>`_ - - -Update website for Beta release -================================ - -* Create the fXX-alpha branch from master - - :: - - fedora-web git:(master) git push origin master:refs/heads/f23-beta - - and checkout to the new branch: - - :: - - fedora-web git:(master) git checkout -t -b f23-beta origin/f23-beta - -* Update the global variables changing ``curr_state`` to Beta for all architectures. - -* Add Beta banner uploading it to ``static/images/banners/f23beta.png`` - which should appear in every ``${PRODUCT}/download/index.html`` page. - Make sure the banner is shown in all sidebars, also in labs, spins, and arm.fp.o. - -* Check all Download links and paths in ``${PRODUCT}/prerelease/index.html`` - You can find all paths in bapp01 (sudo su - mirrormanager first) or - you can look at the downlaod page ``http://dl.fedoraproject.org/pub/alt/stage`` - -* Add CHECKSUM files to ``static/checksums`` and verify that the paths are - correct. The files should be in sundries01 and you can query them with: - - :: - - $ find /pub/fedora/linux/releases/test/23-Beta/ -type f -name \ - *CHECKSUM* -exec cp '{}' . \; - - Remember to add the right checksums to the right websites (same path). - -* Add EC2 AMI IDs for Beta. All IDs now are in the globalvar.py file. - We get all data from there, even the redirect path to trac the AMI IDs. - We now also have a script which is useful to get all the AMI IDs uploaded - with fedimg. Execute it to get the latest uploads, but don't run the script too - early, as new builds are added constantly. - - :: - - fedora-web git:(fXX-beta) python ~/fedora-web/tools/get_ami.py - -* Add CHECKSUM files also to ``http://spins.fedoraproject.org`` in - ``static/checksums``. Verify the paths are correct in ``data/content/verify.html``. - (see point e) to query them on sundries01). Same for labs.fpo and arm.fpo. - -* Remove static/checksums/Fedora-XX-Alpha* in all websites. - -* Verify all paths and links on http://spins.fpo, labs.fpo and arm.fpo. - -* Update Beta Image sizes and pre_cloud_composedate in ``./build.d/globalvar.py``. - Verify they are right in Cloud images and Docker image. - -* Update the new POT files and push them to translation repository every time - you change text strings. - -* Add this build to stg.fedoraproject.org (ansible syncStatic.sh.stg) to - test the pages online. - -* Release Date: - - * Merge the fXX-beta branch to master and correct conflicts manually - * When ready and about 90 minutes before Release Time, push to master - * Tag the commit as new release and push it too: - - :: - - $ git tag -a FXX-Beta -m 'Releasing Fedora XX Beta' - $ git push --tags - - * If needed follow `Fire in the Hole <#fire-in-the-hole>`_ - - -Update website for GA -===================== - -* Create the fXX branch from master - - :: - - fedora-web git:(master) git push origin master:refs/heads/f23 - - and checkout to the new branch: - - :: - - fedora-web git:(master) git checkout -t -b f23 origin/f23 - -* Update the global variables changing ``curr_state`` to '' for all architectures. - -* Check all Download links and paths in ``${PRODUCT}/download/index.html`` - You can find all paths in bapp01 (sudo su - mirrormanager first) or - you can look at the downlaod page ``http://dl.fedoraproject.org/pub/alt/stage`` - -* Add CHECKSUM files to ``static/checksums`` and verify that the paths are - correct. The files should be in sundries01 and you can query them with: - - :: - - $ find /pub/fedora/linux/releases/23/ -type f -name \ - *CHECKSUM* -exec cp '{}' . \; - - Remember to add the right checksums to the right websites (same path). - -* At some point freeze translations. Add an empty PO_FREEZE file to every website's directory you want to freeze. - -* Add EC2 AMI IDs for GA. All IDs now are in the globalvar.py file. - We get all data from there, even the redirect path to trac the AMI IDs. - We now also have a script which is useful to get all the AMI IDs uploaded - with fedimg. Execute it to get the latest uploads, but don't run the script too - early, as new builds are added constantly. - - :: - - fedora-web git:(fXX) python ~/fedora-web/tools/get_ami.py - -* Add CHECKSUM files also to ``http://spins.fedoraproject.org`` in - ``static/checksums``. Verify the paths are correct in ``data/content/verify.html``. - (see point e) to query them on sundries01). Same for labs.fpo and arm.fpo. - -* Remove static/checksums/Fedora-XX-Beta* in all websites. - -* Verify all paths and links on http://spins.fpo, labs.fpo and arm.fpo. - -* Update GA Image sizes and pre_cloud_composedate in ``./build.d/globalvar.py``. - Verify they are right in Cloud images and Docker image. - -* Update static/js/checksum.js and check if the paths and checksum still match. - -* Update the new POT files and push them to translation repository every time - you change text strings. - -* Add this build to stg.fedoraproject.org (ansible syncStatic.sh.stg) to - test the pages online. - -* Release Date: - - * Merge the fXX branch to master and correct conflicts manually - * Add the redirect of prerelease pages in ansible, edit ``ansible/playbooks/include/proxies-redirects.yml``. - * Ask a sysadmin-main to run playbook - * Unfreeze translations by deleting the PO_FREEZE files - * When ready and about 90 minutes before Release Time, push to master - * Update the short links for the Cloud Images for 'Fedora XX', 'Fedora XX-1' and 'Latest' - * Tag the commit as new release and push it too: - - :: - - $ git tag -a FXX -m 'Releasing Fedora XX' - $ git push --tags - - * If needed follow `Fire in the Hole <#fire-in-the-hole>`_ - - -Fire in the hole -================ - -We now use ansible for everything, and normally use a regular build to make -the websites live. If something is not happening as expected, you should get in -contact with a sysadmin-main to run the ansible playbook again. - -All our puppet stuff, such as SyncStatic.sh and SyncTranslation.sh scripts are now -also in ansible! - -Staging server app02 and production server bapp01 do not exist anymore, now our staging -websites are on sundries01.stg and the production on sundries01. Change your scripts -accordingly and as sysadmin-web you should have access to those servers as before. - - -Tips -==== - -* Merging branches - - This can be useful if you're *sure* all new changes on devel branch should go into - the master branch. Conflicts will be solved directly accepting only the changes - in the devel branch. - If you're not 100% sure do a normal merge and fix conflicts manually! - - :: - - $ git merge f23-beta - $ git checkout --theirs f23-beta [list of conflicting po files] - $ git commit diff --git a/preview.sh b/preview.sh new file mode 100755 index 0000000..4270107 --- /dev/null +++ b/preview.sh @@ -0,0 +1,18 @@ +#!/bin/sh + +if [ "$(uname)" = "Darwin" ]; then + # Running on macOS. + # Let's assume that the user has the Docker CE installed + # which doesn't require a root password. + echo "The preview will be available at http://localhost:8080/" + docker run --rm -v "$(pwd):/antora:ro" -v "$(pwd)/nginx.conf:/etc/nginx/conf.d/default.conf:ro" -p 8080:80 nginx + +elif [ "$(expr substr "$(uname -s)" 1 5)" = "Linux" ]; then + # Running on Linux. + # Fedora Workstation has python3 installed as a default, so using that + echo "" + echo "The preview is available at http://localhost:8080" + echo "" + cd ./public + python3 -m http.server 8080 +fi diff --git a/site.yml b/site.yml new file mode 100644 index 0000000..068d093 --- /dev/null +++ b/site.yml @@ -0,0 +1,21 @@ +site: + title: Fedora Websites & Apps + start_page: websites::index +content: + sources: + - url: . + branches: HEAD + start_path: docs +ui: + bundle: + url: https://asamalik.fedorapeople.org/ui-bundle.zip + snapshot: true + default_layout: with_menu +output: + clean: true + dir: ./public + destinations: + - provider: archive +runtime: + pull: true + cache_dir: ./cache