From 04a3617cd21d1c61aa9a1118e949ed5b1fb0681f Mon Sep 17 00:00:00 2001 From: Akashdeep Dhar Date: Apr 14 2022 10:37:43 +0000 Subject: [PATCH 1/4] Add revised content Signed-off-by: Akashdeep Dhar --- diff --git a/docs/antora.yml b/docs/antora.yml index 1c3499b..bc89f15 100644 --- a/docs/antora.yml +++ b/docs/antora.yml @@ -14,5 +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/engg/nav.adoc - modules/dev/nav.adoc diff --git a/docs/modules/ROOT/assets/images/logic-model.png b/docs/modules/ROOT/assets/images/logic-model.png new file mode 100644 index 0000000..75ecc7c Binary files /dev/null and b/docs/modules/ROOT/assets/images/logic-model.png differ diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 0745eda..67e11bf 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1,3 +1,5 @@ -* xref:fedora-release.adoc[Fedora Beta/GA Release] -* xref:translation-flow.adoc[Translation flow] -* xref:fedora-annual-banner.adoc[Fedora Annual Survey Banner] +* xref:index.adoc[Websites & Apps Team] +* xref:objective.adoc[Council Objective] +* xref:tasks.adoc[Our tasks] +* xref:resources.adoc[Resources] +* xref:contact.adoc[Contact us] \ No newline at end of file diff --git a/docs/modules/ROOT/pages/contact.adoc b/docs/modules/ROOT/pages/contact.adoc new file mode 100644 index 0000000..953c5bf --- /dev/null +++ b/docs/modules/ROOT/pages/contact.adoc @@ -0,0 +1,28 @@ +include::ROOT:partial$attributes.adoc[] + += Contact us +:toc: + +Have questions or want to know more? + +== Connect with us + +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:https://chat.fedoraproject.org/#/room/#websites:fedoraproject.org[Fedora Chat] +** link:{COMMS-MATRIX}[Matrix] + +== 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] VCS forge. + +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] diff --git a/docs/modules/ROOT/pages/fedora-annual-banner.adoc b/docs/modules/ROOT/pages/fedora-annual-banner.adoc deleted file mode 100644 index f7ccc8c..0000000 --- a/docs/modules/ROOT/pages/fedora-annual-banner.adoc +++ /dev/null @@ -1,30 +0,0 @@ -= How to add the Fedora Annual Survey Banner - - -== Add into start.fedoraproject.org - -* https://pagure.io/fedora-websites[fedora-websites] repo, https://start.fedoraproject.org[*Start Fedora Project*]: -* data/templates/docs-header.html -* add a div with the link information -* `
` -* NOTE: use col-sm-3 instead of 4 to fit 4 elements -* this will make it consistent with other on the page -* NOTE: for future modifications, check how the text renders when the browser window is smaller or on mobile. -* could be partially fixed by clamping font sizes - -== How to remove the Fedora Annual Survey Banner - -== Removing From start.fedoraproject.org - -* In https://pagure.io/fedora-websites[fedora-websites] repo, go to https://start.fedoraproject.org[*Start Fedora Project*]: -* edit data/templates/docs-header.html -* remove div and containing elements for the survey -* make sure to change the class to `
` - -=== Second method (NOTE MIGHT NOT WORK, CURRENTLY TESTING THIS WITH NEST BANNER) - -* add a image to the data/content/index.html within the grey container -* use the class `col-xs-12 top-margin` and set padding with `style="padding:10px 0"` -* make the image responsive by giving it `style="max-width:832px; width:100%` - - diff --git a/docs/modules/ROOT/pages/fedora-release.adoc b/docs/modules/ROOT/pages/fedora-release.adoc deleted file mode 100644 index 2f9d521..0000000 --- a/docs/modules/ROOT/pages/fedora-release.adoc +++ /dev/null @@ -1,126 +0,0 @@ -= 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 index e1c53bf..44a1e49 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -1,140 +1,74 @@ include::ROOT:partial$attributes.adoc[] = Fedora Websites & Apps -Rick Elrod; Ryan Lerch, Justin W. Flory -:page-authors: {author}, {author_2}, {author_3} :toc: Welcome to the official documentation for the Fedora Websites & Apps Team. - [[about]] == About our team -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: +Our websites being our representation to the wider community of users and contributors over the internet, the team works on designing, developing and maintaining these user-friendly interfaces. The community-led team consists of voluntary contributors from around the world and are involved loosely in 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! +=== Consolidate key Fedora Project websites into a single uniform scheme +In terms of design (look/feel and UI/UX), engineering (tech stack and implementation) and operation (navigation and content), the team attempts to maintain the websites as consistently as possible. -[[about-revamp]] -=== Websites & Apps Community Revamp Objective +=== Develop frontend and backend components of Fedora's web applications +With the use of frontend tools (HTML, CSS, JavaScript and the related frameworks) and backend tools (Python, Ansible, JavaScript and the related frameworks), the team develops the web applications. -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: +=== Making websites as fun and exciting as the project they represent +A book might not be judged by its cover but a project is likely to be judged by the website it is represented by. The team ensures that the websites precisely represent the project's details and offerings. -* 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. +=== Help maintain content that doesn't fall under any particular subproject +The team works on maintaining the content on certain online elements are very generic in nature, like documentation, community wiki, event banners which do not fit in a certain subteam or SIG. + +[[about-revamp]] +== Websites & Apps Community Revamp Objective +The team was rebooted in 2021 as a part of the https://fedoraproject.org/wiki/Objectives/Websites_%26_Apps_Community_Revamp[Websites & Apps Community Revamp Objective]. With the onset of this council objective, the team has been growing ever since with developers, designers and project managers having a wide range of skills and interests. Please refer to [this] documentation to learn more about the council objective's purpose and functions. [[collaborations]] == Our collaborations +In order to work in a community with as many diverse projects and stakeholders as the Fedora Project, the team aims to communicate and collaborate regularly with different community members from various subprojects, SIGs and workgroups within Fedora. The activities on specific websites and applications are coordinated by the relevant points of contacts. -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. - +Here is a list of our active collaborators: -[[work]] -== Our work +[[collaboration-subteams]] +=== Our subteams +The team is further assisted with three subteams that are distinct in function but integrated in purpose. -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. +==== Fedora Websites Revamp Stakeholder Team +The subteam consists of folks from the design team and various other subprojects, SIGs and workgroups where they come up with mockups for the offerings websites, review them and improve upon them continually. -[[work-tasks]] -=== Example tasks +==== Fedora Websites Engineering Team +The subteam looks into the technical side of things - helping with developing and maintaining the websites in the state that they are in for now, assisting with the issue tickets and onboarding/mentoring contributors. -* Adding temporary content to websites -* Coding design mockups provided by the Design Team -* Updating server-side code -* Improving language and accessibility support -* Revamping websites to improve user experience -* Writing documentation for contributors +==== Fedora Websites and Apps Objective Co-leads Team +The subteam looks into the cohesion of the aforementioned two teams - introspecting the current state of the teams, ensure contributors feel rewarded and that the objective outcomes are met. +[[collaborations-subprojects]] +=== Fedora sub-projects -[[bug]] -== Report a bug - -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]. - - - -[[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. - -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] +==== https://fedoraproject.org/wiki/Design[*Design Team*] +The subproject has been actively helping with creating mockups and wireframes, evaluating user interfaces and providing visual content. -== 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. +==== https://fedoraproject.org/wiki/Infrastructure[*Fedora Infrastructure*] +The subproject assists the development and maintenance efforts by providing support on backend technologies and hosting. -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. +==== https://fedoraproject.org/wiki/L10N[*Localization Team*] +The subproject supports with translating content strings across various Fedora Websites and Applications into different languages/dialects. -== 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. +==== https://docs.fedoraproject.org/en-US/mindshare-committee/[*Mindshare Committee*] +There is a representative for the team in the Fedora Mindshare committee for outreach leadership and unifying/sharing working progress. -== Fedora's Website Tech Stacks -* Fedora Community Blog: Wordpress -* Fedora Websites: Flask, Jinja, HTML, CSS3, JavaScript, Python 3 -* Fedora Docs: Asciidoc +==== https://docs.fedoraproject.org/en-US/program_management/[Program Management Team] +The subproject helps plan, schedule, track and coordinate tasks that help achieve the outcomes of the council objective and of the team. -== 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. +[[collaborations-friends]] +=== Friends of Fedora -=== 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. +==== https://docs.fedoraproject.org/en-US/cpe/[*Red Hat Community Platform Engineering team*] +A Red Hat team dedicated to the Fedora and CentOS projects where they contribute to the infrastructure and release engineering. -== 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] +==== 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. diff --git a/docs/modules/ROOT/pages/objective.adoc b/docs/modules/ROOT/pages/objective.adoc new file mode 100644 index 0000000..9121957 --- /dev/null +++ b/docs/modules/ROOT/pages/objective.adoc @@ -0,0 +1,74 @@ +include::ROOT:partial$attributes.adoc[] + += Council Objective +:toc: + +We started off some months ago with a successful objective proposal to put the time and effort into revamping not just the websites and applications that we maintain, but the way the community around it is organized. + +== People involved + +=== Co-leads +* https://fedoraproject.org/wiki/User:T0xic0der[Akashdeep Dhar] +* https://fedoraproject.org/wiki/User:Grahamwhiteuk[Graham White] + +=== Support +* https://fedoraproject.org/wiki/User:Jflory7[Justin W. Flory] +* https://fedoraproject.org/wiki/User:Riecatnor[Marie Nordin] +* https://fedoraproject.org/wiki/User:Siddharthvipul1[Vipul Siddharth] + +=== Other teams +* https://docs.fedoraproject.org/en-US/cpe/[Red Hat Community Platform Engineering] +* https://www.redhat.com/en/blog/channel/red-hat-open-source-program-office[Red Hat Open Source Program Office] + +== Mission +To reboot the websites team to include webapps in the scope of work and set up the team so that they can grow capacity in the future to build new exciting apps to meet community needs. + +=== Logic Model +image::logic-model.png[] + +== Vision +Fedora has an active, engaged team that takes care of our main websites and all of our various community webapps. New folks who show up with an interest in code contributions find this an easy place to jump in. Members of the team are empowered to do the work they’re interested in and are connected to the other parts of the project related to getting those things done. + +== Outcomes +1. The team is happy, excited, recognized, and rewarded. +2. The team has experience and ability with updating legacy Fedora webapps and sites. +3. The Fedora websites are reliably updated when new Fedora Linux releases come out. +4. The team knows what they’re focused on, and that focus meets user needs. +5. Information about Fedora Websites & Apps is accessible and easy to find. +6. It’s easy to find tasks for every skill level and interest. +7. Requests and PRs are handled promptly. +8. Mentorship is available, both for interested new members and for all members needing to get things done in Fedora infrastructure. +9. Websites team is participating in the Mindshare Committee. + +=== Outputs +1. Badges! Team swag! +2. At least one webapp (møte) is modernized, as well as one web site (spins/labs). +3. A documented plan for updating websites on new Fedora Linux releases, with understood team roles and responsibilities. +4. A selected list of apps and websites with service level expectations. The websites in use are the most maintained ones. +5. A continuously curated list of issues and tasks, organized by skillset and interest. +6. Updated Fedora Websites documentation that explains the inventory of websites and how to get involved. +7. A documented process is in plce for making sure requests (both PRs and requests for work) are triaged in a timely manner. +8. "Websites Apprentices" program in place, and connections with Fedora Infrastructure team established. +9. Fedora Mindshare Committee has an active, engaged representative to represent Fedora's Websites & Apps community. + +=== Activities +1. Create team badges https://badges.fedoraproject.org/badge/rock-the-web%21 Request team swag. +2. Develop new version of møte. Update [spins website](https://spins.fedoraproject.org) to new framework. [Link to tasks] +3. Document new release procedures and roles. Document specific team member responsibilities for release days and other critical needs. +4. Inventory the existing apps and websites and decide what can be done about each. Where possible, mark older versions of websites as "outdated" and redirect to proper place. Encourage users (via design, documentation, and communication) towards the newer, maintained tools. +5. Add new modules to the Fedora Websites docs based on different apps. Gradually migrate old docs in GitHub to the Docs repository. +6. Regular meetings for the team that include triaging the W&A repo. [Smaller task: update repo with new tags] +7. Continuous review of incoming work; create reports showing response time and regularly reflect on those metrics. +8. Define Website Apprentice & mentorship role. +9. Create updated process for Web & Apps Team Rep to Mindshare and implement. + +== Resources +1. Badges team to create badges. FCAIC and Design team for team swag. #action riecat +2. Developers working on møte. Infra team or CPE for updating where it runs. Rick to mentor in porting Spins website? +3. Program management team to help with documented processes. (#action bcotton). Docs skills to update team docs.fp.o website (#action relrod+jwf). +4. OSPO and CPE list of existing apps. _Someone_ to build a comprehensive map. Designers to work on best pratices for unified UX. +5. Fedora Docs team for documentation operations ("doc ops"). Websites & Apps team to maintain the documentation content. +6. The team and people interested in doing the triage work. Program Management team may help here too? +7. As #6! +8. Interested team members. Mentorship training provided by Council. +9. Mindshare team to help onboarding. Someone to update docs in project docs. diff --git a/docs/modules/ROOT/pages/old--websites-release.adoc b/docs/modules/ROOT/pages/old--websites-release.adoc deleted file mode 100644 index 2bb52ee..0000000 --- a/docs/modules/ROOT/pages/old--websites-release.adoc +++ /dev/null @@ -1,314 +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 -==== -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/resources.adoc b/docs/modules/ROOT/pages/resources.adoc new file mode 100644 index 0000000..dbadb1c --- /dev/null +++ b/docs/modules/ROOT/pages/resources.adoc @@ -0,0 +1,22 @@ +include::ROOT:partial$attributes.adoc[] + += Resources +:toc: + +The Websites & Apps Team is made up of people who collaborate on all levels of design, operations and technology. They value perspectives, opinions and experiences from a various points of views. Please check out these resources for your own local setup. + +We are continually working to expand our established processes, instructional materials and documentation. + +== Documentation +* link:++https://fedoraproject.org/w/uploads/1/19/Websitesandappsrevamp_logicmodel.png++[Fedora Websites Revamp Logic Model] +* link:++https://developer.fedoraproject.org/tech/languages/python/python-installation.html++[Python - Fedora Developer] +* link:++https://developer.fedoraproject.org/tech/languages/python/flask-installation.html++[Flask - Fedora Developer] +* 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] + +== 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/tasks.adoc b/docs/modules/ROOT/pages/tasks.adoc new file mode 100644 index 0000000..df08af9 --- /dev/null +++ b/docs/modules/ROOT/pages/tasks.adoc @@ -0,0 +1,54 @@ +include::ROOT:partial$attributes.adoc[] + += Our tasks +:toc: + +The team designs, develops and maintains the Fedora's websites and applications. + +These involve a variety of tasks suitable for both newcomers and experienced contributors. + +[[division]] +== Something for everyone +Web technologies, being a very widespread technological stack and an avid point of interest for those involved in marketing, product design, project management etc., the team is in constant need of community contributors who are willing to work on these. + +=== Are you a newcomer to web development? +It is highly recommended for newcomers to web development to join us in our periodic meetings and introduce themselves to start with. According to the level of experience, the team members would help curate issue tickets suitable for them and provide mentorship/guidance wherever necessary in technological stacks like HTML, CSS, JavaScript and Python. This documentation should also consist enough information to help them get started with contributing. + +=== Are you an experienced in web development? +The team often has an array of tickets that demand more advanced knowledge and experience in our technological stack and management operations, and they could always use all the help that we can get. They are always interested to work with developers that bring something new to the table and actively assist in maintaining the status quo of the team. The contributors are requested to participate in the periodic meetings and reach out to the team. + +[[tasks]] +== Example tasks + +=== Adding temporary content to websites +Temporary elements such as beta release indicators on the Fedora Linux offering websites, and banners for surveys and events are to be placed periodically. + +=== Developing approved design mockups +After the design mockups have gone through a review process and ready for implementation, they need to be developed into a final interactive project. + +=== Participating in the periodic meetings +The team connects periodically on a meeting to discuss updates, blockers and plans on activities, either synchronously on call or asynchronously on chat. + +=== Updating server-side code +Websites and applications need to be hosted on a relevant environment (development. staging or deployment), depending on the phase and maturity of the project. + +=== Improving language and accessibility support +This involves working alongside the localization teams for translating the available content to various languages and provide accessibility options. + +=== Revamping websites to improve user experience +In order to keep up with the current internet standards, older websites need to be rebooted using newer design methodologies and tech stacks. + +=== Writing documentation for contributors +Establishing processes and ensuring reproducibility of the activities is better supported by documentation to guide contributors through them. + +=== Creating issue tickets and triaging them +To note the tasks involved in making the aforementioned activities happen and to prioritize them, the team uses certain issue trackers and task boards. + +[[bug]] +== Report a bug + +Did you find a bug on one of our websites? + +Please see these https://fedoraproject.org/wiki/How_to_fix_bugs_on_the_Fedora_Project_website[instructions on fixing bugs]. + +Otherwise, please report them on our https://pagure.io/fedora-websites[repository]. diff --git a/docs/modules/ROOT/pages/translation-flow.adoc b/docs/modules/ROOT/pages/translation-flow.adoc deleted file mode 100644 index adeb1b3..0000000 --- a/docs/modules/ROOT/pages/translation-flow.adoc +++ /dev/null @@ -1,85 +0,0 @@ -= 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/modules/ROOT/partials/attributes.adoc b/docs/modules/ROOT/partials/attributes.adoc index 2015c83..4849d25 100644 --- a/docs/modules/ROOT/partials/attributes.adoc +++ b/docs/modules/ROOT/partials/attributes.adoc @@ -6,7 +6,7 @@ :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 +:comms-video-name: Jitsi 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 deleted file mode 100644 index 9ae8c1d..0000000 --- a/docs/modules/dev/nav.adoc +++ /dev/null @@ -1,3 +0,0 @@ -* 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 deleted file mode 100644 index dacc707..0000000 --- a/docs/modules/dev/pages/index.adoc +++ /dev/null @@ -1,7 +0,0 @@ -= 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 deleted file mode 100644 index f420a04..0000000 --- a/docs/modules/dev/pages/setup-containers.adoc +++ /dev/null @@ -1,68 +0,0 @@ -= 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 deleted file mode 100644 index 3f21132..0000000 --- a/docs/modules/dev/pages/setup.adoc +++ /dev/null @@ -1,97 +0,0 @@ -= 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/engg/assets/images/applications-A.png b/docs/modules/engg/assets/images/applications-A.png new file mode 100644 index 0000000..7b82828 Binary files /dev/null and b/docs/modules/engg/assets/images/applications-A.png differ diff --git a/docs/modules/engg/assets/images/applications-B.png b/docs/modules/engg/assets/images/applications-B.png new file mode 100644 index 0000000..bd62367 Binary files /dev/null and b/docs/modules/engg/assets/images/applications-B.png differ diff --git a/docs/modules/engg/assets/images/websites.png b/docs/modules/engg/assets/images/websites.png new file mode 100644 index 0000000..1a7b2b9 Binary files /dev/null and b/docs/modules/engg/assets/images/websites.png differ diff --git a/docs/modules/engg/nav.adoc b/docs/modules/engg/nav.adoc new file mode 100644 index 0000000..6ea327d --- /dev/null +++ b/docs/modules/engg/nav.adoc @@ -0,0 +1,14 @@ +* xref:index.adoc[Engineering team] +** xref:meetings.adoc[Meetings] +** xref:websites.adoc[Per-project Tech Stack for Websites] +** xref:applications.adoc[Per-project Tech Stack for Applications] +** xref:fedora-annual-banner.adoc[How to add the Fedora Annual Survey Banner] +** xref:old-websites-release.adoc[Websites Release SOP (Legacy)] +** xref:new-fedora-release.adoc[Websites Release SOP (Modern)] +** xref:setup-legacy.adoc[Set up your environment (Legacy)] +** xref:setup-modern.adoc[Set up your environment (Modern)] +** xref:newcontent.adoc[Creating New Content] +** xref:newcontent-edition.adoc[New Edition] +** xref:newcontent-site.adoc[New Site] +** xref:translation-flow.adoc[Translation Flow] +** xref:contact.adoc[Contact us] \ No newline at end of file diff --git a/docs/modules/engg/pages/applications.adoc b/docs/modules/engg/pages/applications.adoc new file mode 100644 index 0000000..bd08455 --- /dev/null +++ b/docs/modules/engg/pages/applications.adoc @@ -0,0 +1,108 @@ +include::engg:partial$attributes.adoc[] + += Per-project Tech Stack for Apps +:toc: + +This document elaborates upon the tech stacks that we use to develop and maintain the applications under our remit. + +[[infographic]] +== Infographic +image:applications-A.png[] +image:applications-B.png[] + +[[remit]] +== Our remit and tools + +Following is a list of applications that we help develop and maintain. + +[[get]] +=== Badges +* Hosted at +* Maintained at + +==== Requires +- Pyramid +- Tahrir API +- Requests +- SQLAlchemy + +=== AskNot-NG +* Hosted at +* Maintained at + +==== Requires +- JavaScript +- Mako +- PyYAML + +=== Elections +* Hosted at +* Maintained at + +==== Requires +- Flask +- Fedora Messaging +- Python Fedora +- FASJSON + +=== Nuancier +* Hosted at +* Maintained at + +==== Requires +- Flask +- JavaScript +- SQLAlchemy +- Python Fedora + +=== Fedocal +* Hosted at +* Maintained at + +==== Requires +- Flask +- Fedora Messaging +- SQLAlchemy +- Python Fedora + +=== Mote +* Hosted at +* Maintained at + +==== Requires +- Flask +- Fedora Messaging +- Bootstrap 5 + +=== Commblog +* Hosted at +* Maintained at + +==== Requires +- Wordpress +- PHP + +=== Easyfix +* Hosted at +* Maintained at + +==== Requires +- Jinja +- Urllib3 +- Bugzilla +- MWClient + +=== Magazine +* Hosted at +* Maintained at + +==== Requires +- Wordpress +- PHP + +=== Ambassador +* Hosted at +* Maintained at + +==== Requires +- TBD diff --git a/docs/modules/engg/pages/contact.adoc b/docs/modules/engg/pages/contact.adoc new file mode 100644 index 0000000..bb0f157 --- /dev/null +++ b/docs/modules/engg/pages/contact.adoc @@ -0,0 +1,28 @@ +include::engg:partial$attributes.adoc[] + += Contact us +:toc: + +Have questions or want to know more? + +== Connect with us + +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:https://chat.fedoraproject.org/#/room/#websites:fedoraproject.org[Fedora Chat] +** link:{COMMS-MATRIX}[Matrix] + +== 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] VCS forge. + +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] diff --git a/docs/modules/engg/pages/fedora-annual-banner.adoc b/docs/modules/engg/pages/fedora-annual-banner.adoc new file mode 100644 index 0000000..3f933ed --- /dev/null +++ b/docs/modules/engg/pages/fedora-annual-banner.adoc @@ -0,0 +1,34 @@ +include::engg:partial$attributes.adoc[] + += How to add the Fedora Annual Survey Banner +:toc: + +== Add into start.fedoraproject.org + +* https://pagure.io/fedora-websites[fedora-websites] repo, https://start.fedoraproject.org[*Start Fedora Project*]: +* data/templates/docs-header.html +* add a div with the link information +* `
` +* NOTE: use col-sm-3 instead of 4 to fit 4 elements +* this will make it consistent with other on the page +* NOTE: for future modifications, check how the text renders when the browser window is smaller or on mobile. +* could be partially fixed by clamping font sizes + +== How to remove the Fedora Annual Survey Banner + +=== Removing From start.fedoraproject.org + +* In https://pagure.io/fedora-websites[fedora-websites] repo, go to https://start.fedoraproject.org[*Start Fedora Project*]: +* edit data/templates/docs-header.html +* remove div and containing elements for the survey +* make sure to change the class to `
` + +=== Second method + +NOTE: MIGHT NOT WORK, CURRENTLY TESTING THIS WITH NEST BANNER + +* add a image to the data/content/index.html within the grey container +* use the class `col-xs-12 top-margin` and set padding with `style="padding:10px 0"` +* make the image responsive by giving it `style="max-width:832px; width:100%` + + diff --git a/docs/modules/engg/pages/index.adoc b/docs/modules/engg/pages/index.adoc new file mode 100644 index 0000000..3228663 --- /dev/null +++ b/docs/modules/engg/pages/index.adoc @@ -0,0 +1,21 @@ +include::engg:partial$attributes.adoc[] + += Fedora Websites & Apps Engineering Team +:toc: + +Welcome to the official documentation for the Fedora Websites & Apps Engineering Team. + +== Points of contact +- https://fedoraproject.org/wiki/User:darknao[Francois Andrieu] +- https://fedoraproject.org/wiki/User:thunderbirdtr[Onuralp Sezer] + +== Purpose +The team takes care maintenance and development of websites and applications while constantly keeping up with UI/UX reviews, mentoring contributors and organizing meetings. + +== Function +1. Multiple contributors from Design team, Server WG, Workstation WG, Kinoite subteam, Fedora Infra subteam, NeuroFedora SIG etc. have been participating in discussions over at the Fedora Websites Revamp 1 chat. +2. Members from the design team have been continually instrumental in coming up with various mockups and improving upon them by getting reviews from within the team and the outer community (Discussion fp.o) +3. Design team representative, Mairin Duffy had been mentoring a set of interns, Emma Kidney and Jess Chitas as well with her endeavours of creating mockups for the Fedora Linux websites. +4. Planning and updates are now recorded in a GitLab subgroup - the creation of which was pursued by the members of this team, contributors from Fedora Infra and those from the Community Platform Engineering team. +5. Meetings have been organized by Pawel Zelawski and participated by the members every after a certain period of time to catch up on the progress, perform stakeholder reviews and plan on the next tasks. +6. With active representation in the events like Nest With Fedora and Fedora Linux Release Parties, the team had been reaching out to garner more feedback on the work done so far and acquire contributors for assistance. diff --git a/docs/modules/engg/pages/meetings.adoc b/docs/modules/engg/pages/meetings.adoc new file mode 100644 index 0000000..1dae37f --- /dev/null +++ b/docs/modules/engg/pages/meetings.adoc @@ -0,0 +1,68 @@ +include::engg:partial$attributes.adoc[] + += Meetings +:toc: + +The team members collaborate periodically over synchronous and asynchronous meetings. + +[[video-conference]] +== Video conference meetings + +The Websites & Apps Engineering Team meets weekly as long as there are at least four active participants available. Should that not be the case - updates, plans and blockers are conveyed asynchronously in the Fedora Chat channel by the members. + +[[conference-details]] +== Details +* Location - link:{COMMS-VIDEO}[*{COMMS-VIDEO-NAME} room*] +* Day - *{MEETING-DAY}s* +* Time - *{MEETING-TIME}* + +[[agenda]] +== Agenda +A video conference meeting is a fleeting afair and hence, it is important to use every moment of the meeting wisely to discuss important topics. + +=== Flow of discussion +* [_5-10m_] Roll call / greetings / welcomes +* [_5m_] Any announcements to share with group? +* [_5m_] Follow-ups on past actions, if any +* [_10m_] Engineering updates +* [_10m_] Council Objective updates +* [_remaining_] Discussion on plans and blockers +* Pick a chair for next time! +* [_5m before end_] Wrap-up, open floor discussion + +=== Example +The following is a Markdown-styled example agenda to extend from. +[source] +---- +## FORMAT + +### Chair +- ADD YOUR NAME(S) HERE + +### Attendees +- ADD YOUR NAME(S) HERE + +### Check up +- How are you doing? +- How's the weather there? + +### Agenda +- ADD ITEMS HERE +---- + +[[guidelines]] +== Participation guidelines +* Please focus on listening, and on appreciating what others are trying to say, not only on what you are hearing. +* Wherever possible, please refrain from multitasking on email or social media and strive to remain fully present and tuned in to what others are saying and feeling. +* Please assume best intent in everyone's comments and strive to keep a constructive tone in your own. +* Please use simple, accessible language. In particular, please avoid jargon and acronyms, so that all may fully participate. +* When you speak, please make just one point and then let others speak. We want everyone to have an equal chance to speak. In a group of "n" people, speak no more than "1/nth" of the time. +* Please speak for yourself when making comments, using "I". Please don't speak for the assembled group by speaking as "we". +* Help us be mindful of the schedule and stay on time; we anticipate many people will have much they want to say, but please support us in moving the dialog forward. + +[[self-aware]] +== Please be a self-aware participant! +* Please indicate you want to speak by raising your hand on video or with the button in Jitsi Meet; if you are not able to use or raise your hand, feel free to speak up but please try not to interrupt others. +* Stay muted when you are not speaking. +* Please be mindful of background noise and join the call from a quiet location. Construction sites, windy gardens and non-quarantined internet cafes do not qualify as quiet locations. +* All parents and caregivers shall enjoy an irrevocable "background/foreground kid and dependent noise" exception at all times, but muting etiquette still applies. diff --git a/docs/modules/engg/pages/new-fedora-release.adoc b/docs/modules/engg/pages/new-fedora-release.adoc new file mode 100644 index 0000000..ff3f2b1 --- /dev/null +++ b/docs/modules/engg/pages/new-fedora-release.adoc @@ -0,0 +1,126 @@ +include::engg:partial$attributes.adoc[] + += Fedora Release (Modern) + +== 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/engg/pages/newcontent-edition.adoc b/docs/modules/engg/pages/newcontent-edition.adoc new file mode 100644 index 0000000..3fc3a68 --- /dev/null +++ b/docs/modules/engg/pages/newcontent-edition.adoc @@ -0,0 +1,90 @@ +include::engg:partial$attributes.adoc[] + += New Edition +: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/engg/pages/newcontent-site.adoc b/docs/modules/engg/pages/newcontent-site.adoc new file mode 100644 index 0000000..290ad52 --- /dev/null +++ b/docs/modules/engg/pages/newcontent-site.adoc @@ -0,0 +1,16 @@ +include::engg:partial$attributes.adoc[] + += Creating A New Site +: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/engg/pages/newcontent.adoc b/docs/modules/engg/pages/newcontent.adoc new file mode 100644 index 0000000..530f516 --- /dev/null +++ b/docs/modules/engg/pages/newcontent.adoc @@ -0,0 +1,24 @@ +include::engg:partial$attributes.adoc[] + += Creating New Content +: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/modules/engg/pages/old-websites-release.adoc b/docs/modules/engg/pages/old-websites-release.adoc new file mode 100644 index 0000000..5cdc531 --- /dev/null +++ b/docs/modules/engg/pages/old-websites-release.adoc @@ -0,0 +1,316 @@ +include::engg:partial$attributes.adoc[] + += Websites Release (Legacy) +:toc: + +== 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: 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/engg/pages/setup-legacy.adoc b/docs/modules/engg/pages/setup-legacy.adoc new file mode 100644 index 0000000..8a81357 --- /dev/null +++ b/docs/modules/engg/pages/setup-legacy.adoc @@ -0,0 +1,97 @@ +include::engg:partial$attributes.adoc[] + += Set up your environment (old way) +: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-modern.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/engg/pages/setup-modern.adoc b/docs/modules/engg/pages/setup-modern.adoc new file mode 100644 index 0000000..8d6e76e --- /dev/null +++ b/docs/modules/engg/pages/setup-modern.adoc @@ -0,0 +1,68 @@ +include::engg:partial$attributes.adoc[] + += Set up your environment (using containers) +: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/engg/pages/translation-flow.adoc b/docs/modules/engg/pages/translation-flow.adoc new file mode 100644 index 0000000..a7113c6 --- /dev/null +++ b/docs/modules/engg/pages/translation-flow.adoc @@ -0,0 +1,83 @@ +include::engg:partial$attributes.adoc[] + += Translation flow (for Fedora websites) +:toc: + +== 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/modules/engg/pages/websites.adoc b/docs/modules/engg/pages/websites.adoc new file mode 100644 index 0000000..e40640a --- /dev/null +++ b/docs/modules/engg/pages/websites.adoc @@ -0,0 +1,125 @@ +include::engg:partial$attributes.adoc[] + += Per-project Tech Stack for Websites +:toc: + +This document elaborates upon the tech stacks that we use to develop and maintain the websites under our remit. + +[[infographic]] +== Infographic +image:websites.png[] + +[[remit]] +== Our remit + +Following is a list of websites that we help develop and maintain. + +[[get]] +=== GetFedora +* Hosted at https://getfedora.org/ +* Maintained at https://pagure.io/fedora-web/websites/ + +[[spins]] +=== Fedora Spins +* Hosted at https://spins.fedoraproject.org/ +* Maintained at https://pagure.io/fedora-websites/blob/main/f/spins.fedoraproject.org + +[[labs]] +=== Fedora Labs +* Hosted at https://labs.fedoraproject.org/ +* Maintained at https://pagure.io/fedora-websites/blob/main/f/spins.fedoraproject.org + +[[arm]] +=== Fedora ARM +* Hosted at https://arm.fedoraproject.org/ +* Maintained at https://pagure.io/fedora-websites/blob/main/f/arm.fedoraproject.org + +[[alt]] +=== Fedora Alternative Downloads +* Hosted at https://alt.fedoraproject.org/ +* Maintained at https://pagure.io/fedora-websites/blob/main/f/alt.fedoraproject.org + +[[community]] +=== Fedora Community +* Hosted at https://fedoracommunity.org/ +* Maintained at https://pagure.io/fedora-websites/blob/main/f/fedoracommunity.org/ + +[[start]] +=== Fedora Start +* Hosted at https://start.fedoraproject.org/ +* Maintained at https://pagure.io/fedora-websites/blob/main/f/start.fedoraproject.org + +[[flock]] +=== Flock to Fedora +* Hosted at https://flocktofedora.org/ +* Maintained at https://pagure.io/fedora-websites/blob/main/f/flocktofedora.org + +[[docs]] +=== Fedora Docs +* Hosted at https://docs.fedoraproject.org/en-US/docs/ +* Maintained at https://docs.fedoraproject.org/en-US/docs/ + +[[tools]] +== Our tools + +Following is a list of tools that we make use of. + +[[genshi]] +=== Genshi +Genshi is a template engine for XML-based vocabularies written in Python. Genshi is used to easily insert generated output into XML-based languages, usually HTML, and reuse elements between documents. Genshi's syntax is based on Kid, but its architecture is different. + +[[lxml]] +=== LXML +The lxml XML toolkit is a Pythonic binding for the C libraries libxml2 and libxslt. It is unique in that it combines the speed and XML feature completeness of these libraries with the simplicity of a native Python API, mostly compatible but superior to the well-known ElementTree API. + +[[jinja]] +=== Jinja +Jinja is a web template engine for the Python programming language. It was created by Armin Ronacher and is licensed under a BSD License. Jinja is similar to the Django template engine but provides Python-like expressions while ensuring that the templates are evaluated in a sandbox. + +[[frozen]] +=== Frozen Flask +Frozen-Flask freezes a Flask application into a set of static files. The result can be hosted without any server-side software other than a traditional web server. Frozen-Flask is only about deployment: you can use Frozen-Flask to only have static HTML files on your server. + +[[rss]] +=== Python RSS +RSS (Rich Site Summary) is a format for delivering regularly changing web content. Many news-related sites, weblogs and other online publishers syndicate their content as an RSS Feed to whoever wants it. Feedparser and similar libraries are made use of while using Python 3. + +[[flask]] +=== Flask +Flask is a micro web framework written in Python. It is classified as a microframework because it does not require particular tools or libraries. It has no database abstraction layer, form validation, or any other components where pre-existing third-party libraries provide common functions. + +[[scss]] +=== SCSS/CSS +SCSS stands for the Sassy Cascading Style Sheets. The more advanced variant of CSS is SCSS. It was created by Chris Eppstein and Natalie Weizenbaum and designed by Hampton Catlin. It is also referred to as Sassy CSS due to its advanced features. + +[[python]] +=== Python 3 +Python is a high-level, general-purpose programming language. Its design philosophy emphasizes code readability with the use of significant indentation. Its language constructs and object-oriented approach aim to help programmers write clear, logical code for small and large-scale projects. + +[[antora]] +=== Antora +Antora is a modular, multi-repository site generator designed for creating documentation sites from content composed in AsciiDoc® and processed with Asciidoctor. Antora’s toolchain and workflow help documentation and engineering teams manage documentation sites. + +[[asciidoctor]] +=== AsciiDoctor +Asciidoctor is a fast, open source, Ruby-based text processor for parsing AsciiDoc® into a document model and converting it to output formats such as HTML 5, DocBook 5, manual pages, PDF, EPUB 3, and other formats. Docs of the said format are fed into Antora for being parsed. + +[[make]] +=== Make +In software development, Make is a build automation tool that automatically builds executable programs and libraries from source code by reading files called Makefiles which specify how to derive the target program. It remains widely used amidst the more prevalent IDE build features. + +[[podman]] +=== Podman +Podman is an open-source project that is available on most Linux platforms and resides on GitHub. Podman is a daemonless container engine for developing, managing, and running Open Container Initiative (OCI) containers and container images on your Linux System. + +[[ansible]] +=== Ansible +Ansible is an open-source software provisioning, configuration management, and application-deployment tool enabling infrastructure as code. It runs on many Unix-like systems, and can configure both Unix-like systems as well as Microsoft Windows. + +[[html]] +=== HTML +The HyperText Markup Language or HTML is the standard markup language for documents designed to be displayed in a web browser. It can be assisted by technologies such as Cascading Style Sheets and scripting languages such as JavaScript for enhancing the design or adding interactivity. + +[[javascript]] +=== JavaScript +JavaScript, often abbreviated JS, is a programming language that is one of the core technologies of the World Wide Web, alongside HTML and CSS. Over 97% of websites use JavaScript on the client side for web page behavior, often incorporating third-party libraries. diff --git a/docs/modules/engg/pages/websites.png b/docs/modules/engg/pages/websites.png new file mode 100644 index 0000000..1a7b2b9 Binary files /dev/null and b/docs/modules/engg/pages/websites.png differ diff --git a/docs/modules/engg/partials/attributes.adoc b/docs/modules/engg/partials/attributes.adoc new file mode 100644 index 0000000..4849d25 --- /dev/null +++ b/docs/modules/engg/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: Jitsi Meet +:meeting-day: Tuesday +:meeting-time: 15:00 - 16:00 UTC +:year: 2021 diff --git a/docs/modules/runbook/nav.adoc b/docs/modules/runbook/nav.adoc deleted file mode 100644 index aeb4473..0000000 --- a/docs/modules/runbook/nav.adoc +++ /dev/null @@ -1,5 +0,0 @@ -* 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 deleted file mode 100644 index 0e866e2..0000000 --- a/docs/modules/runbook/pages/index.adoc +++ /dev/null @@ -1,16 +0,0 @@ -= 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 deleted file mode 100644 index 7be33dd..0000000 --- a/docs/modules/runbook/pages/meetings.adoc +++ /dev/null @@ -1,35 +0,0 @@ -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 deleted file mode 100644 index 0ce0554..0000000 --- a/docs/modules/runbook/pages/newcontent-edition.adoc +++ /dev/null @@ -1,90 +0,0 @@ -= 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 deleted file mode 100644 index f00d396..0000000 --- a/docs/modules/runbook/pages/newcontent-site.adoc +++ /dev/null @@ -1,16 +0,0 @@ -= 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 deleted file mode 100644 index 08caded..0000000 --- a/docs/modules/runbook/pages/newcontent.adoc +++ /dev/null @@ -1,24 +0,0 @@ -= 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/site.yml b/site.yml index 068d093..9a2474d 100644 --- a/site.yml +++ b/site.yml @@ -17,5 +17,5 @@ output: destinations: - provider: archive runtime: - pull: true + fetch: true cache_dir: ./cache From 27d0b61e83a985f8586acf5cc48208fbb49c86d4 Mon Sep 17 00:00:00 2001 From: Akashdeep Dhar Date: Apr 14 2022 10:54:46 +0000 Subject: [PATCH 2/4] Remove redundant table of contents Signed-off-by: Akashdeep Dhar --- diff --git a/docs/modules/ROOT/pages/contact.adoc b/docs/modules/ROOT/pages/contact.adoc index 953c5bf..3d4e481 100644 --- a/docs/modules/ROOT/pages/contact.adoc +++ b/docs/modules/ROOT/pages/contact.adoc @@ -1,7 +1,6 @@ include::ROOT:partial$attributes.adoc[] = Contact us -:toc: Have questions or want to know more? diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 44a1e49..2fb883a 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -1,7 +1,6 @@ include::ROOT:partial$attributes.adoc[] = Fedora Websites & Apps -:toc: Welcome to the official documentation for the Fedora Websites & Apps Team. diff --git a/docs/modules/ROOT/pages/objective.adoc b/docs/modules/ROOT/pages/objective.adoc index 9121957..d62cee2 100644 --- a/docs/modules/ROOT/pages/objective.adoc +++ b/docs/modules/ROOT/pages/objective.adoc @@ -1,7 +1,6 @@ include::ROOT:partial$attributes.adoc[] = Council Objective -:toc: We started off some months ago with a successful objective proposal to put the time and effort into revamping not just the websites and applications that we maintain, but the way the community around it is organized. diff --git a/docs/modules/ROOT/pages/resources.adoc b/docs/modules/ROOT/pages/resources.adoc index dbadb1c..be51261 100644 --- a/docs/modules/ROOT/pages/resources.adoc +++ b/docs/modules/ROOT/pages/resources.adoc @@ -1,7 +1,6 @@ include::ROOT:partial$attributes.adoc[] = Resources -:toc: The Websites & Apps Team is made up of people who collaborate on all levels of design, operations and technology. They value perspectives, opinions and experiences from a various points of views. Please check out these resources for your own local setup. diff --git a/docs/modules/ROOT/pages/tasks.adoc b/docs/modules/ROOT/pages/tasks.adoc index df08af9..e5e381f 100644 --- a/docs/modules/ROOT/pages/tasks.adoc +++ b/docs/modules/ROOT/pages/tasks.adoc @@ -1,7 +1,6 @@ include::ROOT:partial$attributes.adoc[] = Our tasks -:toc: The team designs, develops and maintains the Fedora's websites and applications. diff --git a/docs/modules/engg/pages/applications.adoc b/docs/modules/engg/pages/applications.adoc index bd08455..ba0825f 100644 --- a/docs/modules/engg/pages/applications.adoc +++ b/docs/modules/engg/pages/applications.adoc @@ -1,7 +1,6 @@ include::engg:partial$attributes.adoc[] = Per-project Tech Stack for Apps -:toc: This document elaborates upon the tech stacks that we use to develop and maintain the applications under our remit. diff --git a/docs/modules/engg/pages/contact.adoc b/docs/modules/engg/pages/contact.adoc index bb0f157..b75dd99 100644 --- a/docs/modules/engg/pages/contact.adoc +++ b/docs/modules/engg/pages/contact.adoc @@ -1,7 +1,6 @@ include::engg:partial$attributes.adoc[] = Contact us -:toc: Have questions or want to know more? diff --git a/docs/modules/engg/pages/fedora-annual-banner.adoc b/docs/modules/engg/pages/fedora-annual-banner.adoc index 3f933ed..84b5a5b 100644 --- a/docs/modules/engg/pages/fedora-annual-banner.adoc +++ b/docs/modules/engg/pages/fedora-annual-banner.adoc @@ -1,7 +1,6 @@ include::engg:partial$attributes.adoc[] = How to add the Fedora Annual Survey Banner -:toc: == Add into start.fedoraproject.org diff --git a/docs/modules/engg/pages/index.adoc b/docs/modules/engg/pages/index.adoc index 3228663..854fe06 100644 --- a/docs/modules/engg/pages/index.adoc +++ b/docs/modules/engg/pages/index.adoc @@ -1,7 +1,6 @@ include::engg:partial$attributes.adoc[] = Fedora Websites & Apps Engineering Team -:toc: Welcome to the official documentation for the Fedora Websites & Apps Engineering Team. diff --git a/docs/modules/engg/pages/meetings.adoc b/docs/modules/engg/pages/meetings.adoc index 1dae37f..e96692e 100644 --- a/docs/modules/engg/pages/meetings.adoc +++ b/docs/modules/engg/pages/meetings.adoc @@ -1,7 +1,6 @@ include::engg:partial$attributes.adoc[] = Meetings -:toc: The team members collaborate periodically over synchronous and asynchronous meetings. diff --git a/docs/modules/engg/pages/old-websites-release.adoc b/docs/modules/engg/pages/old-websites-release.adoc index 5cdc531..32a0767 100644 --- a/docs/modules/engg/pages/old-websites-release.adoc +++ b/docs/modules/engg/pages/old-websites-release.adoc @@ -1,7 +1,6 @@ include::engg:partial$attributes.adoc[] = Websites Release (Legacy) -:toc: == Preparing the website for a new release cycle diff --git a/docs/modules/engg/pages/translation-flow.adoc b/docs/modules/engg/pages/translation-flow.adoc index a7113c6..7db5cab 100644 --- a/docs/modules/engg/pages/translation-flow.adoc +++ b/docs/modules/engg/pages/translation-flow.adoc @@ -1,7 +1,6 @@ include::engg:partial$attributes.adoc[] = Translation flow (for Fedora websites) -:toc: == General diff --git a/docs/modules/engg/pages/websites.adoc b/docs/modules/engg/pages/websites.adoc index e40640a..11a84b5 100644 --- a/docs/modules/engg/pages/websites.adoc +++ b/docs/modules/engg/pages/websites.adoc @@ -1,7 +1,6 @@ include::engg:partial$attributes.adoc[] = Per-project Tech Stack for Websites -:toc: This document elaborates upon the tech stacks that we use to develop and maintain the websites under our remit. From 4d669e7a3d530f0f37e137a7a7b90bf3e98c1d99 Mon Sep 17 00:00:00 2001 From: Akashdeep Dhar Date: Apr 19 2022 13:33:22 +0000 Subject: [PATCH 3/4] Complete the list of applications Signed-off-by: Akashdeep Dhar --- diff --git a/docs/modules/engg/pages/applications.adoc b/docs/modules/engg/pages/applications.adoc index ba0825f..30f9cd0 100644 --- a/docs/modules/engg/pages/applications.adoc +++ b/docs/modules/engg/pages/applications.adoc @@ -14,10 +14,14 @@ image:applications-B.png[] Following is a list of applications that we help develop and maintain. -[[get]] +''' + === Badges -* Hosted at +* Hosted at https://badges.fedoraproject.org/ * Maintained at + - https://github.com/fedora-infra/fedbadges + - https://github.com/fedora-infra/tahrir + - https://github.com/fedora-infra/tahrir-api ==== Requires - Pyramid @@ -25,18 +29,22 @@ Following is a list of applications that we help develop and maintain. - Requests - SQLAlchemy +''' + === AskNot-NG -* Hosted at -* Maintained at +* Hosted at http://whatcanidoforfedora.org/ +* Maintained at https://github.com/fedora-infra/asknot-ng ==== Requires - JavaScript - Mako - PyYAML +''' + === Elections -* Hosted at -* Maintained at +* Hosted at https://elections.fedoraproject.org/ +* Maintained at https://github.com/fedora-infra/elections ==== Requires - Flask @@ -44,9 +52,11 @@ Following is a list of applications that we help develop and maintain. - Python Fedora - FASJSON +''' + === Nuancier -* Hosted at -* Maintained at +* Hosted at https://apps.fedoraproject.org/nuancier/ +* Maintained at https://github.com/fedora-infra/nuancier ==== Requires - Flask @@ -54,9 +64,11 @@ Following is a list of applications that we help develop and maintain. - SQLAlchemy - Python Fedora +''' + === Fedocal -* Hosted at -* Maintained at +* Hosted at https://calendar.fedoraproject.org/ +* Maintained at https://github.com/fedora-infra/fedocal ==== Requires - Flask @@ -64,26 +76,31 @@ Following is a list of applications that we help develop and maintain. - SQLAlchemy - Python Fedora +''' + === Mote -* Hosted at -* Maintained at +* Hosted at https://meetbot.fedoraproject.org/ +* Maintained at https://github.com/fedora-infra/mote ==== Requires - Flask - Fedora Messaging - Bootstrap 5 +''' + === Commblog -* Hosted at -* Maintained at +* Hosted at https://communityblog.fedoraproject.org/ ==== Requires - Wordpress - PHP +''' + === Easyfix -* Hosted at -* Maintained at +* Hosted at https://fedoraproject.org/easyfix/ +* Maintained at https://pagure.io/fedora-gather-easyfix ==== Requires - Jinja @@ -91,17 +108,22 @@ Following is a list of applications that we help develop and maintain. - Bugzilla - MWClient +''' + === Magazine -* Hosted at -* Maintained at +* Hosted at https://fedoramagazine.org/ ==== Requires - Wordpress - PHP +''' + === Ambassador -* Hosted at -* Maintained at +* Hosted at https://fedoracommunity.org/ +* Maintained at https://pagure.io/fedora-websites/blob/main/f/fedoracommunity.org ==== Requires - TBD + +''' \ No newline at end of file From 4af5efc33c224a562e1c9cf3b49b53da3f3932e6 Mon Sep 17 00:00:00 2001 From: Akashdeep Dhar Date: Apr 27 2022 05:55:52 +0000 Subject: [PATCH 4/4] Add docs - Chairing meetings and Mindshare rep Signed-off-by: Akashdeep Dhar --- diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 67e11bf..77c373a 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1,5 +1,6 @@ * xref:index.adoc[Websites & Apps Team] * xref:objective.adoc[Council Objective] * xref:tasks.adoc[Our tasks] +* xref:representatives.adoc[Representatives] * xref:resources.adoc[Resources] * xref:contact.adoc[Contact us] \ No newline at end of file diff --git a/docs/modules/ROOT/pages/representatives.adoc b/docs/modules/ROOT/pages/representatives.adoc new file mode 100644 index 0000000..9430636 --- /dev/null +++ b/docs/modules/ROOT/pages/representatives.adoc @@ -0,0 +1,42 @@ +include::ROOT:partial$attributes.adoc[] + += Representatives + +The Websites and Apps Team is currently looking for a representative to Mindshare. If you happen to be interested in being one, please reach out to our channels to express your interest and we can take the discussion further from there. The responsibilities of the representative involves representing the team to the Mindshare committee and collaborate with other groups/teams/SIGs that work with them. Being a conduit between the two teams, the representative is expected to invest a fair amount of time and have good communication skills. + +== Representatives + +=== Current representative +* We are looking for one. + +=== Previous representatives +* Rick Elrod + +== Responsibilities + +Representatives are critical in keeping communication between the team and Mindshare flowing. As a Mindshare representative, you will be involved in the following activities: + +- Participate in the fedora-mindshare IRC/Matrix channel's weekly meetups +- In the fedora-mindshare Pagure repo, review and comment on tickets +- Work closely with the representatives from the other outreach teams to ensure that the most effective decisions are made +- Give the Mindshare Committee valuable input +- Share best practises: one of Mindshare's objectives is to remove any hurdles or impediments to sharing best practises +- Ascertain that the team is represented, and bring any challenges or barriers they may encounter to Mindshare meetings +- Ascertain that the Fedora budget is managed efficiently across all locations +- Listen to the Fedora community's needs, problems, and hopes and transmit them to the Mindshare Committee + +== Duration of service +The service will last for two Fedora release cycles, or a year. However, depending on the personal circumstances of those serving as Representatives, terms may be shorter or longer. In the odd case that the representative(s), Mindshare Committee, or the Websites and Apps Team choose to change representation, they must show appropriate justification. The Websites and Apps Team will then choose a new representative based on the SOP. + +== Selection +This section outlines the process of nominating and selecting representatives. The selection procedure outlined below begins when a current representative, the Mindshare committee, or the Fedora Council requests a rotation of representatives. + +=== Nomination +Potential delegates will have a two-week period to nominate themselves. Nominees can be self-nominated or nominated with the approval of other members of the Websites and Apps Team. Nominees must be members of the said team, have a basic understanding of various Fedora sub-projects, and have enough time to complete the essential obligations. + +If no nominees are found, the Websites and Apps Team will collaborate with the Mindshare Committee to extend the search message and request more time. If no nominees are discovered after that, the role will be rotated among current Websites and Apps Team members until a new representative is found. + +== Teams you will be closely working with +- Fedora Mindshare +- Websites and Apps Team and Subteams +- Various other Outreach teams as required diff --git a/docs/modules/engg/pages/meetings.adoc b/docs/modules/engg/pages/meetings.adoc index e96692e..f33bfe1 100644 --- a/docs/modules/engg/pages/meetings.adoc +++ b/docs/modules/engg/pages/meetings.adoc @@ -20,14 +20,17 @@ The Websites & Apps Engineering Team meets weekly as long as there are at least A video conference meeting is a fleeting afair and hence, it is important to use every moment of the meeting wisely to discuss important topics. === Flow of discussion -* [_5-10m_] Roll call / greetings / welcomes +* [_5m_] Roll call / greetings / welcomes * [_5m_] Any announcements to share with group? * [_5m_] Follow-ups on past actions, if any * [_10m_] Engineering updates * [_10m_] Council Objective updates + - [_3m_] Mindshare updates + - [_3m_] Stakeholder updates + - [_4m_] General discussion * [_remaining_] Discussion on plans and blockers * Pick a chair for next time! -* [_5m before end_] Wrap-up, open floor discussion +* [_5m before end_] Wrap-up and open floor discussion === Example The following is a Markdown-styled example agenda to extend from. @@ -49,6 +52,27 @@ The following is a Markdown-styled example agenda to extend from. - ADD ITEMS HERE ---- +== How to chair team meetings? +Anyone can be a chair for the Websites and Apps Engineering Team, and we encourage everyone to try chairing our weekly team meetings at least once to get an experience. The team is supportive of newcomers and experienced folks alike who are trying to chair a meeting for the first time so one needs not worry about anything going wrong midway. + +The chair should + +* Be one of the first ones to join the meeting as they would be the ones coordinating with the attendees and carrying the meeting forward +* Have the agenda document open on a side to read topics from, add names to the agenda list and make notes/summaries/action-items discussed on +* Make sure that all the points from the slated agenda are discussed during the meeting and that the action items, if any, are accounted for +* Ensure that the attendees feel comfortable enough and get a fair amount of time to put their points forward and that there points are considered +* Act as an arbitrator to settle disputes, if there are any, among the attendees and try best to reach the middle ground by avoiding conflicts. +* Keep track of "raised hands" in order to ensure that every attendee in the meeting get their opportunity to speak in the order of "hands raised" +* Let the team know well in advance if they are not able to make it to the meeting that they volunteered to chair for to help get a replacement +* Attempt to prevent diversions in the meeting, be them caused by either themselves or the attendees and try to maximally utilize the meeting time +* Motivate communication in an accessible manner - so folks who are unwilling to use camera and/or microphone should be encouraged to use the chat +* Conduct an in-meeting poll, discussion, opinions, debate in an unbiased and fair manner to all the attendees to avoid any possible conflicts +* Feel comfortable to pass on their turn to someone else mid-meeting, should something important come up or if they cannot attend anymore +* Avoid a survivorship bias by passing on the updates shared and progresses made on the meeting to the wider community using relevant channels +* Make notes on the developments made in a meeting, summarize discussions, plans and action items, or find an assignee from the attendees to do it +* Ensure that they are attending the meeting from a noise-free and disturbance-free environment and are not distracted by any other work or social media +* Use an accessible and simple vocabulary to convey their statements for maximum participation, and wait enough after each point for attendees to reflect + [[guidelines]] == Participation guidelines * Please focus on listening, and on appreciating what others are trying to say, not only on what you are hearing. @@ -62,6 +86,6 @@ The following is a Markdown-styled example agenda to extend from. [[self-aware]] == Please be a self-aware participant! * Please indicate you want to speak by raising your hand on video or with the button in Jitsi Meet; if you are not able to use or raise your hand, feel free to speak up but please try not to interrupt others. -* Stay muted when you are not speaking. +* Please stay muted when you are not speaking. * Please be mindful of background noise and join the call from a quiet location. Construction sites, windy gardens and non-quarantined internet cafes do not qualify as quiet locations. * All parents and caregivers shall enjoy an irrevocable "background/foreground kid and dependent noise" exception at all times, but muting etiquette still applies.