#617 Add a guide to pushing badges
Closed 4 years ago by jflory7. Opened 4 years ago by churchyard.

file added
+74
@@ -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/<name>.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.

+ 

It is not ideal, but at least it is something.

There is an open pull request with documentation in the quick-docs repository here:

https://pagure.io/fedora-docs/quick-docs/pull-request/36

It would be a good idea to reconcile the two documents and publish them somewhere. There is also the existing Infrastructure documentation on pushing a badge:

https://docs.pagure.org/infra-docs/sysadmin-guide/sops/badges.html

@kevin suggested we use the final publishing place as the infra-docs repository, which contains all the SOPs for Fedora Infrastructure. Perhaps we should start with a shared Etherpad with the existing content and work on updating the existing documentation in infra-docs to be more complete and updated for 2018.

What do you all think?


cc: @nb @asamalik @bex @sayanchowdhury et al

As long as the docs is linked from here, i don't mind where it is. Until now, i had no idea some docs existed, so i've just summarized what I've learned yesterday (mostly for myself). Feel free to take parts of it, ditch it, or use it, but please make sure that it is clear form this repo, how we are pushing badges, I bet Fedora non-admins have no idea.

I used these instructions to push a manually awarded badges. They worked. I believe we should:

  1. Edit this PR for additional information in the Quick Docs PR and some typos.
  2. Close the QuickDocs PR as I believe this set of instructions contains most of that.
  3. Push the final doc here as it is the place where the consumers of that information are located.

Opinions?

After prior conversations with @sayanchowdhury, @nb, @churchyard, and others, we decided to make the final resting place for Fedora Badges sysadmin documentation in the Infra infra-docs repository, where there is already a Fedora Badges how-to document, albeit being from 2014.

See infra-docs#119 for the updated content.

I am closing this PR. 🎬

Pull-Request has been closed by jflory7

4 years ago
Metadata
Changes Summary 1