| |
@@ -0,0 +1,283 @@
|
| |
+ = How to push Fedora Badges
|
| |
+ :toc:
|
| |
+
|
| |
+ == Architecture
|
| |
+
|
| |
+ The badge-awarding back-end daemon, https://github.com/fedora-infra/fedbadges[fedbadges], wakes up when it receives a http://fedmsg.com/en/stable/[fedmsg] event.
|
| |
+ It compares that message and the history in https://github.com/fedora-infra/datanommer[datanommer] against a series of rules.
|
| |
+ If a contributor matches the criteria described in one of those rules, then they are awarded a badge.
|
| |
+
|
| |
+ The front-end is a web application called https://github.com/fedora-infra/tahrir[Tahrir].
|
| |
+ It mostly is just an interface for users to look at their badges.
|
| |
+ However, it also has an admin interface for manually adding new badges, awarding badges, and creating "invitations" (QR codes) for badges.
|
| |
+
|
| |
+ The badge-awarding back-end daemon, https://github.com/fedora-infra/fedbadges[fedbadges], runs on the `badges-backend01` node.
|
| |
+ The process is `fedmsg-hub` and logs are in `/var/log/fedmsg/fedmsg-hub.log`.
|
| |
+
|
| |
+ The front-end runs under `apache/mod_wsgi` on `badges-web0{1,2}` nodes.
|
| |
+
|
| |
+ === Upstream documentation
|
| |
+
|
| |
+ * For a detailed description of how the fedbadges daemon works, see the https://github.com/fedora-infra/fedbadges/blob/develop/README.rst[fedbadges README].
|
| |
+ * For a diagram of the interacting pieces in the Fedora Badges system, see the https://github.com/fedora-infra/fedbadges/blob/develop/diagrams/[fedbadges diagrams].
|
| |
+
|
| |
+
|
| |
+ == Sysadmin process: How to push a Badge
|
| |
+
|
| |
+ Pushing badges consists of two operations:
|
| |
+
|
| |
+ . Push badge assets (`.png`, `.svg`, `.yaml`) to https://pagure.io/fedora-badges[fedora-badges] repository
|
| |
+ . Add badge to https://badges.fedoraproject.org/[badges.fedoraproject.org]
|
| |
+
|
| |
+ Anyone with write permissions to https://pagure.io/fedora-badges[fedora-badges] can push badges.
|
| |
+ Pull requests can also be used.
|
| |
+ Only members of the `sysadmin-badges` FAS group _and_ xref:add-tahrir-admins[admins of the web interface] can add badges.
|
| |
+
|
| |
+ Badge artists and badge developers should push design assets (`png` and `svg` art) and rules (`yaml`) to the https://pagure.io/fedora-badges[fedora-badges] repository.
|
| |
+
|
| |
+ === Preparing to create a badge
|
| |
+
|
| |
+ Once a badge is approved by the Design Team and has the https://pagure.io/fedora-badges/issues?status=Open&tags=ready+to+push[ready to push] tag, they are ready to be pushed.
|
| |
+ Follow this checklist to push a new badge:
|
| |
+
|
| |
+ . Ensure artwork is *approved* by Design Team
|
| |
+ . Ensure name and description of badge are clear
|
| |
+ . Ensure one of these requirements is met:
|
| |
+ ** _Manually awarded badges_: What FAS accounts receive permissions to award badge
|
| |
+ ** _Awarded via fedmsg rule_: YAML file with rules is present
|
| |
+
|
| |
+ If you are confused or something is missing, comment on the issue and remove the *ready to push* tag.
|
| |
+
|
| |
+ === Add badge assets to Pagure
|
| |
+
|
| |
+ . Download artwork and rule file (if applicable):
|
| |
+ ** Double-check the artwork is actually the final version from ticket
|
| |
+ ** Open / view both art files to check they are not corrupt (in the past, corrupt images were accidentally pushed)
|
| |
+ . Give both art and rule files the *same name*, place into https://pagure.io/fedora-badges/blob/master/f/pngs[pngs/], https://pagure.io/fedora-badges/blob/master/f/svgs[svg/], https://pagure.io/fedora-badges/blob/master/f/rules[rules/] directories
|
| |
+ . _On request only_: Generate a STL file for 3D-printing a badge:
|
| |
+ ** Change directories into `bin/` and run `export.sh`.
|
| |
+ This creates a STL file for the badge and moves it to the correct place.
|
| |
+ ** Check the `README` file in `bin/` for more info about the script.
|
| |
+ . Commit all files and push to https://pagure.io/fedora-badges[fedora-badges] (or make a PR)
|
| |
+
|
| |
+ Make sure files have a reasonable name (e.g. `all-lowercase-dashes-only.png`).
|
| |
+ Some types of badges follow a naming convention, like FAS group membership badges (i.e. `fas-badge-name.png`) or Koji build badges (i.e. `koji-badge-name.png`).
|
| |
+ Follow past precedent where possible.
|
| |
+ Later, the file name is used for the file on the front-end server (e.g. `https://badges.fedoraproject.org/pngs/all-lowercase-dashes-only.png`).
|
| |
+
|
| |
+ === Push assets to back-end server via Ansible
|
| |
+
|
| |
+ _Note_: All assets must be in the `master` branch of https://pagure.io/fedora-badges[fedora-badges] before proceeding.
|
| |
+ You must also be a member of `sysadmin-badges` in FAS for this to work.
|
| |
+
|
| |
+ Next, you need to move all assets from the Pagure repository to the back-end server.
|
| |
+ This is done via an https://infrastructure.fedoraproject.org/cgit/ansible.git/tree/playbooks/manual/push-badges.yml[Ansible playbook] from the `batcave` server.
|
| |
+ Follow these steps to push the assets to production.
|
| |
+
|
| |
+ . SSH into `batcave01.phx2.fedoraproject.org`
|
| |
+ . Run the playbook: `sudo rbac-playbook manual/push-badges.yml`
|
| |
+ . Enter FAS password and https://docs.pagure.org/infra-docs/sysadmin-guide/sops/2-factor.html[2FA token]
|
| |
+ . Once finished, ensure badge is now publicly visible (i.e. `https://badges.fedoraproject.org/pngs/<name>.png`)
|
| |
+
|
| |
+ === Add automatically-awarded badges
|
| |
+
|
| |
+ _Note_: Pay close attention when following these steps.
|
| |
+ It is easy to create a badge, but much harder to edit it later.
|
| |
+ Double-check information is entered correctly in the YAML file on first go, or else you have to write SQL statements to fix it later.
|
| |
+
|
| |
+ Automatically awarded badges are created by the YAML rule file.
|
| |
+ Once the Ansible playbook finishes, the badge is created and placed in the https://badges.fedoraproject.org/explore/badges[badges index].
|
| |
+ The only part _not_ created automatically are tags (see xref:badge-metadata[Badge metadata] below for info about tags).
|
| |
+ To add new tags, find the badge on https://badges.fedoraproject.org/[badges.fedoraproject.org].
|
| |
+ If you are logged in as an admin, there is a text field to enter in new tags.
|
| |
+
|
| |
+ === Add manually-awarded badges
|
| |
+
|
| |
+ _Note_: Pay close attention when following these steps.
|
| |
+ It is easy to create a badge, but much harder to edit it later.
|
| |
+ Double-check information is entered correctly on first go, or else you have to write SQL statements to fix it later.
|
| |
+
|
| |
+ Once the badge assets are pushed to the back-end, add the badge to the front-end, [.title-ref]#Tahrir#.
|
| |
+ The front-end is hosted at https://badges.fedoraproject.org/[badges.fedoraproject.org].
|
| |
+ Follow these steps to add the badge in Tahrir.
|
| |
+
|
| |
+ . Open _Admin_ interface on https://badges.fedoraproject.org/[badges.fedoraproject.org]
|
| |
+ . Go to the _Add badge_ section.
|
| |
+ . Enter in all information as provided in the badge ticket (see xref:badge-metadata[Badge metadata] below.)
|
| |
+ . Double-check all entered information is *correct and accurate*
|
| |
+ . Click _Create badge_ to create new badge
|
| |
+
|
| |
+ The badge is now created.
|
| |
+ You should be able to find in the https://badges.fedoraproject.org/explore/badges[badges index].
|
| |
+
|
| |
+ ==== Grant authorizations
|
| |
+
|
| |
+ Manually-awarded badges require authorized users to issue a badge.
|
| |
+ You can do this at the bottom of the _Admin_ interface, near _Create Authorizations_.
|
| |
+ Add the person to receive awarding privileges into the _Person Email_ field.
|
| |
+ *This must be formatted as their fedoraproject.org email address* (e.g. FASuser [at] fedoraproject [dot] org).
|
| |
+ For badge name, use the slug (or badge name) from the URL of the badge (e.g. for https://badges.fedoraproject.org/badge/commops-superstar[badges.fedoraproject.org/badge/commops-superstar], this is `commops-superstar`).
|
| |
+
|
| |
+ To add multiple users, repeat this process for each user.
|
| |
+
|
| |
+ [[badge-metadata]]
|
| |
+ === Badge metadata
|
| |
+
|
| |
+ * *Name*: name of the badge – this determines URL of badge, so triple-check for typos
|
| |
+ * *Image*: full link to the PNG (e.g. `https://badges.fedoraproject.org/pngs/all-lowercase-dashes-only.png`)
|
| |
+ * *Description*: badge description text (ensure there is _no_ hanging whitespace)
|
| |
+ * *Criteria*: link to the issue in https://pagure.io/fedora-badges[fedora-badges]
|
| |
+ * *Issuer*: keep the default
|
| |
+ * *Tags*: comma-delimited list of tags:
|
| |
+ ** *Review other similar badges to ensure tags are correct.*
|
| |
+ Some tags are special and function as categories.
|
| |
+ ** *Follow past precedent* for tags.
|
| |
+ Avoid creating new tags if at all possible.
|
| |
+ ** Removing tags _is not_ easy.
|
| |
+ Adding them later _is_ easy.
|
| |
+
|
| |
+ ==== Close out the ticket
|
| |
+
|
| |
+ After pushing the badge, do some last checks to make sure the badge pushed correctly.
|
| |
+ Make sure the page is viewable and double-check that it is categorized correctly in the https://badges.fedoraproject.org/explore/badges[badges index].
|
| |
+
|
| |
+ Return to the Pagure issue for the badge.
|
| |
+ Post a link to the pushed badge.
|
| |
+ If you granted authorizations, list the FAS usernames you granted authorizations to.
|
| |
+ After commenting, closing the issue as *pushed*.
|
| |
+
|
| |
+ Congratulations, you just pushed your very own Fedora Badge!
|
| |
+
|
| |
+
|
| |
+ == How to manually award a badge
|
| |
+
|
| |
+ To perform this, you must be in the `sysadmin-badges` FAS group.
|
| |
+
|
| |
+ There is a script installed on `badges-backend01` in `/usr/local/bin/award-badge`.
|
| |
+ It has help options that you can pull up with `award-badge -h`.
|
| |
+ It takes a required `--user FAS_USERNAME` and a required `--badge BADGE_ID` option.
|
| |
+ For example, the following invocation would award the "Associate Editor" badge to "ralph":
|
| |
+
|
| |
+ [source,bash]
|
| |
+ ----
|
| |
+ sudo /usr/local/bin/award-badge --user ralph --badge associate-editor
|
| |
+ ----
|
| |
+
|
| |
+ The `BADGE_ID` for a badge can be found by visiting its page on the web UI.
|
| |
+ That badge can be found at `https://badges.fedoraproject.org/badge/associate-editor`.
|
| |
+
|
| |
+ The `award-badge` script and source code is managed by ansible.git.
|
| |
+ The source code is in https://infrastructure.fedoraproject.org/cgit/ansible.git/tree/roles/badges/backend/files/award-badge[roles/badges/backend/files/award-badge].
|
| |
+
|
| |
+ Often enough, there is need for a workflow to batch award a badge to a number of people.
|
| |
+ For instance, the _Keepin' Fedora Beautiful_ badge comes from a member of the Design Team posting a ticket with a list of FAS usernames (i.e. https://pagure.io/fedora-badges/issue/129[fedora-badges#129]).
|
| |
+
|
| |
+ For cases, like that you can `wget` the file with the list of FAS usernames on `badges-backend01` and run something like:
|
| |
+
|
| |
+ [source,bash]
|
| |
+ ----
|
| |
+ $ for i in $(cat keepingbeautiful-list ) ; do
|
| |
+ sudo /usr/local/bin/award-badge --user $i --badge keepin-fedora-beautiful-f20;
|
| |
+ done
|
| |
+ ----
|
| |
+
|
| |
+
|
| |
+ [[manually-revoke-badge]]
|
| |
+ == How to manually revoke a badge or authorization
|
| |
+
|
| |
+ You may revoke badge or badge authorizations in a similar fashion to the `award-badges` script.
|
| |
+ You may chain the invocation of the `revoke-badge` or `revoke-authorization` script in the same manner as the `award-badges` script.
|
| |
+
|
| |
+ .Revoking a badge:
|
| |
+ [source,bash]
|
| |
+ ----
|
| |
+ sudo /usr/local/bin/revoke-badge --user ralph --badge associate-editor
|
| |
+ ----
|
| |
+
|
| |
+ .Revoking an authorization:
|
| |
+ [source,bash]
|
| |
+ ----
|
| |
+ sudo /usr/local/bin/revoke-authorization --user ralph --badge associate-editor
|
| |
+ ----
|
| |
+
|
| |
+
|
| |
+ [[add-tahrir-admins]]
|
| |
+ == How to add admins to Tahrir
|
| |
+
|
| |
+ It would be nice if we could automatically grant admin access in the web interface to members of the `sysadmin-badges` FAS group.
|
| |
+ We currently do not have this feature and must maintain the list of web UI admins separately.
|
| |
+
|
| |
+ The configuration file for the badges front-end web app is managed by ansible.git.
|
| |
+ The source code is in https://infrastructure.fedoraproject.org/cgit/ansible.git/tree/roles/badges/frontend/templates/tahrir.ini[roles/badges/frontend/templates/tahrir.ini].
|
| |
+
|
| |
+ In that file, find the `tahrir.admin` option.
|
| |
+ It is a comma-separated list of email addresses that, when logged in, should be granted rights to access the admin panels at https://badges.fedoraproject.org/[badges.fedoraproject.org].
|
| |
+
|
| |
+ To add a new admin, add their `FAS_USERNAME@fedoraproject.org` email to that line, commit, and push.
|
| |
+ Use Ansible to run the `groups/badges-web.yml` playbook to push the config change out to the web front-end nodes.
|
| |
+
|
| |
+
|
| |
+ == How to create an invitation and QR code
|
| |
+
|
| |
+ This is done through the admin panel of the web interface (although we can probably write a script for it to be used on the back-end node).
|
| |
+
|
| |
+ Invitations / QR codes are typically created for Fedora events.
|
| |
+ For instance at the Flock 2013 Fedora Contributors conference, we created a badge to award attendees.
|
| |
+ We followed the procedure below to generate an invitation and a QR code.
|
| |
+ Next, the QR code was distributed to conference organizers.
|
| |
+ They added the QR code to the program brochure that each attendee was given.
|
| |
+ Then, any attendee that scanned the code was redirected on their phone to the badges app, where they were awarded the badge.
|
| |
+
|
| |
+ === Create an invitation
|
| |
+
|
| |
+ . Make sure you are an admin in the web interface and logged into https://badges.fedoraproject.org/[badges.fedoraproject.org]
|
| |
+ . Click the _Admin_ link in the UI
|
| |
+ . Under the _Invitations_ section, add this information:
|
| |
+ ** *Creation Date*: Optional.
|
| |
+ It defaults to the current date.
|
| |
+ ** *Expiration Date*: Optional, but you probably want to specify one.
|
| |
+ It defaults to 2 hours from the current time.
|
| |
+ For instance, at the Flock 2013 conference, we set the expiration date at the end of the conference.
|
| |
+ Anyone who tried to claim the badge with the QR code after that time would be denied, with the message _this invitation is expired_.
|
| |
+ ** *Badge ID*: "ID" of the badge you want to award.
|
| |
+ See the xref:manually-revoke-badge[section above] for how to find a badge ID.
|
| |
+ ** *Person email*: Email of a person in the badges database.
|
| |
+ In our case, use their Fedora email (e.g. `FAS_USERNAME@fedoraproject.org`).
|
| |
+
|
| |
+ Now, the user you specified will have a link to the QR code and invite link on their profile page.
|
| |
+ They can take initiative to distribute and share the badge as they wish.
|
| |
+
|
| |
+
|
| |
+ == Useful scripts for manual work
|
| |
+
|
| |
+ See `ansible/roles/badges/backend/files/` for the motherload.
|
| |
+ These all get deployed to `/usr/local/bin/` on `badges-backend01` where you can login to execute them.
|
| |
+
|
| |
+ *edit-badge*::
|
| |
+ Update the description and the criteria link for a badge.
|
| |
+ Useful in the event you created it incorrectly, or if feedback from other stakeholders requires us to change something.
|
| |
+ *award-badge*::
|
| |
+ Award a badge to a specific user.
|
| |
+ *revoke-badge*::
|
| |
+ Removes a badge from a user to whom it has been awarded erroneously.
|
| |
+ *Remember!* If you revoke a badge award from a user, you should also give them the `consolation-prize` badge as a token of apology.
|
| |
+ *grant-authorization*::
|
| |
+ Grant authorization rights on a badge to a privileged user.
|
| |
+ They can then create invitation links and QR codes for that badge as well as award it directly to other users from the web interface.
|
| |
+ *revoke-authorization*::
|
| |
+ Revoke those authorization rights for a user on a given badge.
|
| |
+
|
| |
+
|
| |
+ == Contact information
|
| |
+
|
| |
+ Owner:::
|
| |
+ Fedora Badges community
|
| |
+
|
| |
+ Contact:::
|
| |
+ #fedora-badges
|
| |
+
|
| |
+ Servers:::
|
| |
+ badges-web0*, badges-backend0*
|
| |
+
|
| |
+ Purpose:::
|
| |
+ Award "badges" to Fedora Contributors
|
| |
jflory7
commented 4 years ago
This commit moves the Fedora Infra Docs SOP originally written in
ReStructuredText into an AsciiDoc file in the Badges docs site:
https://docs.pagure.org/infra-docs/sysadmin-guide/sops/badges.html
Once this is merged into fedora-badges.git, I will follow up with a PR
to the infra-docs.git repository to point to the new home of the SOP so
there are not multiple sources of truth published at the same time.
Also I tested all of the internal links and validated that they work.