Como enviar insígnias do Fedora

Arquitetura

O daemon back-end de premiação de insígnias, fedbadges, desperta quando recebe um evento do fedmsg. Ele compara essa mensagem e o histórico em datanommer com uma série de regras. Se um colaborador atender aos critérios descritos em uma dessas regras, ele receberá uma insígnia.

O front-end é um aplicativo web chamado Tahrir. Em geral, é apenas uma interface para os usuários verem suas insígnias. No entanto, ele também possui uma interface administrativa para adicionar manualmente novas insígnias, atribuir insígnias e criar "convites" (códigos QR) para insígnias.

O daemon back-end de premiação de insígnia, fedbadges, é executado no nó badges-backend01. O processo é fedmsg-hub e os logs estão em /var/log/fedmsg/fedmsg-hub.log.

O front-end é executado em apache/mod_wsgi nos nós badges-web0{1,2}.

Documentação upstream

  • Para obter uma descrição detalhada de como o daemon fedbadges funciona, consulte fedbadges README.

  • Para obter um diagrama das peças que interagem no sistema Fedora Badges, consulte os diagramas do fedbadges.

Processo de administrador de sistema: como enviar uma insígnia

Enviar insígnias consiste em duas operações:

  1. Enviar os ativos da insígnia (.png, .svg, .yaml) para o repositório fedora-badges

  2. Adicionar insígnia ao badges.fedoraproject.org

Qualquer pessoa com permissão de gravação para fedora-badges pode enviar insígnias. Pull requests também podem ser usadas. Apenas membros do grupo FAS sysadmin-badges e administradores da interface web podem adicionar insígnias.

Artistas e desenvolvedores de insígnias devem enviar recursos de design (arte png e svg) e regras (yaml) para o repositório fedora-badges.

Preparando-se para criar uma insígnia

Assim que uma insígnia é aprovada pela Equipe de Design e tem a tag ready to push, elas estão prontas para serem enviadas. Siga esta lista de verificação para enviar uma nova insígnia:

  1. Certifique-se de que a arte seja aprovada pela Equipe de Design

  2. Certifique-se de que o nome e a descrição da insígnia sejam claras

  3. Certifique-se de que um destes requisitos seja atendido:

    • Insígnias premiadas manualmente: Quais contas FAS recebem permissões para premiar insígnia

    • Premiadas por meio de regra do fedmsg: Arquivo YAML com regras está presente

Se você estiver confuso ou algo estiver faltando, comente sobre o problema e remova a tag ready to push.

Adicionar ativos de insígnia ao Pagure

  1. Baixe a arte e o arquivo de regras (se aplicável):

    • Verifique se a arte é realmente a versão final do ticket

    • Abra / visualize ambos os arquivos de arte para verificar se não estão corrompidos (no passado, imagens corrompidas eram enviadas acidentalmente)

  2. Dê aos arquivos de arte e regra o mesmo nome, coloque nos diretórios pngs/, svg/, rules/

  3. Somente se pedido: Gere um arquivo STL para impressão em 3D da insígnia:

    • Mude os diretórios para bin/ e execute export.sh. Isso cria um arquivo STL para o crachá e o move para o local correto.

    • Verifique o arquivo README em bin/ para mais informações sobre o script.

  4. Faça commit de todos os arquivos e push para fedora-badges (ou faça um PR)

Certifique-se de que os arquivos tenham um nome razoável (por exemplo, tudo-minúsculo-apenas-tracejado.png). Alguns tipos de insígnia seguem uma convenção de nomenclatura, como insígnias de associação de grupo FAS (ou seja, fas-nome-insígnia.png) ou insígnia de compilação no Koji (isto é, koji-nome-insígnia.png). Siga os precedentes anteriores sempre que possível. Posteriormente, o nome do arquivo é usado para o arquivo no servidor front-end (por exemplo, https://badges.fedoraproject.org/pngs/tudo-minúsculo-apenas-tracejado.png).

Enviar ativos para o servidor back-end via Ansible

Nota: Todos os ativos devem estar no branch master de fedora-badges antes de prosseguir. Você também deve ser um membro de sysadmin-badges no FAS para que isso funcione.

Em seguida, você precisa mover todos os ativos do repositório Pagure para o servidor backend. Isso é feito por meio de um playbook Ansible do servidor batcave. Siga estas etapas para colocar os ativos em produção.

  1. Use SSH para acessar batcave01.iad2.fedoraproject.org

  2. Execute o playbook: sudo rbac-playbook manual/push-badges.yml

  3. Insira a senha FAS e o token2FA

  4. Uma vez finalizado, certifique-se que a insígnia agora esteja publicamente visível (isto é, https://badges.fedoraproject.org/pngs/<nome>.png)

Adicionar insígnias premiadas automaticamente

Nota: Preste muita atenção ao seguir essas etapas. É fácil criar uma insígnia, mas muito mais difícil editá-la posteriormente. Verifique novamente se as informações foram inseridas corretamente no arquivo YAML na primeira vez, ou então você terá que escrever instruções SQL para corrigi-las mais tarde.

As insígnias atribuídas automaticamente são criadas pelo arquivo de regras YAML. Assim que o playbook do Ansible terminar, a insígnia é criada e colocada no índice de insígnias. A única parte não criada automaticamente são as tags (veja metadados do insígnia abaixo para obter informações sobre as tags). Para adicionar novas tags, encontre a insígnia em badges.fedoraproject.org. Se você estiver conectado como administrador, há um campo de texto para inserir novas tags.

Adicionar insígnias premiadas manualmente

Nota: Preste muita atenção ao seguir essas etapas. É fácil criar uma insígnia, mas muito mais difícil editá-lo posteriormente. Verifique novamente se as informações foram inseridas corretamente na primeira vez, ou então você terá que escrever instruções SQL para corrigi-las mais tarde.

Assim que os ativos da insígnia forem colocadas no back-end, adicione a insígnia ao front-end, Tahrir. O front-end está hospedado em badges.fedoraproject.org. Siga estas etapas para adicionar a insígnia ao Tahrir.

  1. Abra a interface Admin em badges.fedoraproject.org

  2. Acesse a seção Add badge.

  3. Insira todas as informações como fornecido no ticket da insígnia (veja Metadados de insígnia abaixo.)

  4. Verifique novamente se todas as informações inseridas estão corretas e precisas

  5. Clique em Create badge para criar a nova insígnia

A insígnia agora está criado. Você deve conseguir encontrá-la no índice de insígnias.

Conceder autorizações

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 badges.fedoraproject.org/badge/commops-superstar, this is commops-superstar).

To add multiple users, repeat this process for each user.

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 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 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":

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 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. 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:

$ for i in $(cat keepingbeautiful-list ) ; do
    sudo /usr/local/bin/award-badge --user $i --badge keepin-fedora-beautiful-f20;
done

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:
sudo /usr/local/bin/revoke-badge --user ralph --badge associate-editor
Revoking an authorization:
sudo /usr/local/bin/revoke-authorization --user ralph --badge associate-editor

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 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 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

  1. Make sure you are an admin in the web interface and logged into badges.fedoraproject.org

  2. Click the Admin link in the UI

  3. 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 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

Proprietário

Fedora Badges community

Contato

#fedora-badges

Servidores

badges-web0*, badges-backend0*

Propósito

Award "badges" to Fedora Contributors

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