From b2d9ce616b66a6402a57e50c30e08712ac9d384d Mon Sep 17 00:00:00 2001 From: Miro Hrončok Date: May 04 2018 08:21:05 +0000 Subject: Add a guide to pushing badges --- diff --git a/PUSHING.md b/PUSHING.md new file mode 100644 index 0000000..001e723 --- /dev/null +++ b/PUSHING.md @@ -0,0 +1,74 @@ +# How to push badges + +Pushing badges consist of 2 operations: + + 1. pushing badge assets (png, svg, yaml) to this repository + 2. adding the badge to [badges.fedoraproject.org](https://badges.fedoraproject.org/) + +Anyone with write permissions to this repository can do 1. Pull Request can be utilized even. Only members of the _sysadmin-badges_ group in FAS can do 2 (fact check: more stuff was needed). + +## Getting a badge to push + +Once a badge is approved and has the [ready to push](https://pagure.io/fedora-badges/issues?status=Open&tags=ready+to+push) tag, they are ready to be pushed. + +Check the issue with the badge proposal. Here is a good checklist: + + * **artwork** was approved + * double check you know what files (png+svg) are final. it's usually the latest ones, but not always + * it is clear what is the badge **name** and **description** + * the badge is one of the following: + * manually awarded (events etc.): it is clear **who shall award the badge** + * automatically awarded (via fedmsg): it has a **yml file with rules** + +If you are confused or something is missing, comment on the issue and remove the _ready to push_ tag. + +## Adding the badge assets to this repository + +Put the png into the [pngs folder](https://pagure.io/fedora-badges/blob/master/f/pngs), svg into the [svgs folder](https://pagure.io/fedora-badges/blob/master/f/svgs) and finally, if the badge is automatically awarded, put the yml file with rules into the [rules directory](https://pagure.io/fedora-badges/blob/master/f/rules). + +Make sure the files have reasonable name (`all-lowercase-dashes-only.png`) and that all have the same name (except the extension). Check that the `image_url` in yml definition is reasonable (i.e. uses the same name). + + * `https://badges.fedoraproject.org/pngs/all-lowercase-dashes-only.png` + +Make sure that `discussion` points to the right ticket: + + * `https://pagure.io/design/issue/74` + +(With manually awarded badges, there is nothing to check, don't worry.) + +Push to **master** if you can, or **create a Pull Request** if you cannot. + +## Adding the badge to badges.fedoraproject.org + +(The assets need to be in **master** before you start to work on this.) + +First, setup an [OTP token](https://admin.fedoraproject.org/totpcgiprovision) for your FAS account (only needed when you are doing this for the first time). +Second, setup [SSH config](https://docs.pagure.org/infra-docs/sysadmin-guide/sops/sshaccess.html) (also, only for the first time). Contact Fedora Admins, if you cannot SSH into batcave (`ssh batcave01.phx2.fedoraproject.org`). + +SSH into batcave. Run `sudo rbac-playbook manual/push-badges.yml` - that synces the badges assets from this repo into the Interwebz. When asked for Password and token, use your FAS password immediately followed by the token (no spaces, no plus, just put it right next to the password). It takes a minute or two. When done, you should be able to see the png file of you badge online at `https://badges.fedoraproject.org/pngs/.png`. Time to congratulate yourself or panic, depending on whether it worked or not. + +Once the assets are synced, the procedure differs for manually awarded badges and automatically awarded badges. + +### Manually awarded badges + +Go to [badges.fedoraproject.org/admin](https://badges.fedoraproject.org/admin) (you should have an _Admin_ link on badges website). Go into the _Badges_ section. Fill in the badge details: + + * **Name**: the name of the badge – this will determine the URL of the badge, so tripple check for typos + * **Image**: full link to the PNG, e.g. `https://badges.fedoraproject.org/pngs/all-lowercase-dashes-only.png` + * **Description**: badge description + * **Criteria**: Link to the issue in this repo + * **Issuer**: keep the default + * **Tags**: Comma-delimited list of tags. Use other badges for inspiration. Tags define the category as well, so be careful. Removing tags is not easy unfortunately. Adding them later is easy. + +After adding the badge, see the [Badge Index](https://badges.fedoraproject.org/explore) and find your badge. Check the URL and copy the part that is not common with other badges (i.e. the slug of the badge's name), e.g. `all-lowercase-dashes-only`. + +In [Admin](https://badges.fedoraproject.org/admin), go to the _Create Authorizations_ section. Add the person, who should give the badge into the _Person Email_ field (use their fedoraproject.org e-mail address). Put the badge slug from previous paragraph into the _Badge ID_ field. You can do this multiple times for multiple users. + +That's it. Post the badge link to the issue and close it as pushed. It's a good idea to remind the reporters about who can award the badge. + +### Automatically awarded badges + +The rules file defines almost everything so teh badge is automatically available in the [Badge Index](https://badges.fedoraproject.org/explore). Find it the new badge, go to it's detail and add tags. Use other badges for inspiration. Tags define the category as well, so be careful. Removing tags is not easy unfortunately. Adding them later is easy. + +That's it. Post the badge link to the issue and close it as pushed. +