Traduções: English - Português (Brasil)


Documentação

Documentação do Salsa

Salsa é uma plataforma de desenvolvimento colaborativa dentro do Debian.

Suporte

In case you encounter any problems with Salsa, to get support you may want to join us :

... they may help you.

Usuários(as)

Registre uma conta em https://salsa.debian.org/users/sign_up

Sua conta será bloqueada até que um(a) administrador(a) gitlab a habilite. O procedimento em julho de 2021 é que você receba um e-mail confirmando a validação da sua conta. Por favor, seja paciente.

Contas não utilizadas por DDs antes de maio de 2020

Antes de maio de 2020, todos(as) os(as) desenvolvedores(as) Debian tinham contas criadas para eles(as) usando o nome de usuário(a) Debian. Contas que nunca tinham sido utilizadas e nem tiveram senhas configuradas foram desativadas. Aquelas contas somente podem ser usadas após serem ativadas adequadamente. Por favor, use qualquer um dos canais de suporte. Após a reativação, uma nova senha pode ser definida através da redefinição de senha.

Grupos

Usuários(as) e grupos compartilham o mesmo espaço de nomes. Para prevenir conflitos com nomes de usuários(as), nós forçamos aos grupos um sufixo '-team' (equipe), com exceção do grupo 'Debian', que todos(as) os(as) desenvolvedores(as) Debian são participantes.

Para criar um grupo, faça login na página de registro de equipe. Também existe um link para ela na página de registro: se você não estiver logado(a) ainda, será solicitado(a) a fazê-lo e posteriormente redirecionado(a).

Manutenção colaborativa: grupo "Debian"

O grupo debian serve para CollaborativeMaintenance (manutenção colaborativa, o antigo collab-maint no Alioth). O grupo é acessível a todos(as) os(as) desenvolvedores(as) Debian por padrão, que são automaticamente adicionados(as) com nível de acesso Maintainer (mantenedor(a)). Commits diretos aos repositórios no grupo Debian por qualquer desenvolvedor(a) Debian são implicitamente bem vindos. Nenhuma coordenação pré-commit (por exemplo, merge-request ou e-mail) são esperados.

Usuários(as) externos(as) (desenvolvedores(as) não Debian) precisam solicitar acesso de escrita para os repositórios dentro do grupo debian de um(a) desenvolvedor(a) Debian que conheçam, ou de seu(sua) padrinho/madrinha. O acesso deve ser garantido para projetos individuais e não para todo o grupo Debian.

Projetos sob o grupo debian não podem ser transferidos ou apagados por qualquer pessoa, somente por administradores(as) do Salsa. No caso de precisar apagar um projeto ou tê-lo transferido para outro espaço de nomes, por favor entre em contato com a administração do Salsa através do canal de suporte. Veja a seção Suporte para informações de contato.

URLs canônicas

As URLs canônicas para uso no debian/control são:

Vcs-Browser: https://salsa.debian.org/<usuário(a)-ou-equipe>/<pacote>
Vcs-Git: https://salsa.debian.org/<usuário(a)-ou-equipe>/<pacote>.git

onde <usuário(a)-ou-equipe> é

  • alice para uma usuária salsa Alice Desenvolvedora <alice@exemplo.com>

  • debian para o espaço de nomes Debian/ (o equivalente ao collab-maint no alioth)

  • foobar-team para a Equipe de Empacotamento Foobar

Você pode instruir o git a reescrever as URLs em URLs ssh que podem ser enviadas:

git config --global url."git@salsa.debian.org:".pushInsteadOf "https://salsa.debian.org/"

Isto funcionará para todos os repositórios salsa acessados via URLs https:// no presente, passado e futuro.

Você também pode usar um atalho para todos os repositórios Salsa:

git config --global url."git@salsa.debian.org:".insteadOf salsa:

Desta forma, você pode usar uma linha de comando mais curta:

git clone salsa:debian/htop

Projetos e repositórios

No GitLab, um projeto é um repositório Git, e cada repositório Git requer um projeto. Você pode criar diversos projetos no mesmo espaço de nomes (usuário(a) ou grupo).

Notificações por e-mail

Cada proprietário(a) de projeto pode habilitar um "e-mail ao enviar" (email on push). Para fazer isso, vá até as configurações do projeto → integrações (integrations) → serviços de projeto (project services) → e-mail ao fazer push (emails on push) e configure a lista de destinatários(as) que receberão os e-mails.

Especialmente ao encaminhar e-mails para tracker.debian.org, adicione dispatch@tracker.debian.org para os(as) destinatários(as) (ou, se por alguma não tão boa razão, o nome do projeto não é o nome do pacote-fonte, dispatch+${pacote}_vcs@tracker.debian.org (onde ${pacote} é o nome do pacote-fonte)).

Leve em consideração que a atual implementação envia um único e-mail a cada push com todos os commits reunidos, o que torna-o um pouco inútil para qualquer fluxo de trabalho pós-revisão. Isto está sendo acompanhado no desenvolvimento do GitLab em https://gitlab.com/gitlab-org/gitlab-ce/issues/19901.

Informações sobre manipulação de bugs por e-mail

O GitLab tem muitos comandos de texto, também conhecidos como "ações rápidas (quick actions) que podem ser usados ao se interagir com o GitLab por e-mail. A maioria das coisas podem ser feitas via e-mail ao se responder para as notificações de e-mail. Existem endereços de e-mail especiais para criação de merge requests e problemas (issues).

Notificações IRC

Irker

Alexander Wirt está patrocinando uma instância Irker. Ela pode ser habilitada com a integração irker disponível em Configurações (Settings)/Integrações (Integrations)/Irker. Por favor, use as seguintes configurações:

Na parte de destinatários(as), adicione uma lista separada por quebra de linha dos destinatários(as)/canais. Se seu canal é protegido por chave, use a sintaxe nome-do-canal?key=qualquer-coisa, omitindo o sinal # inicial (se não omitir o sinal #, o Irker se juntará ao canal chamado literalmente #nome-do-canal?key=qualquer-coisa, e assim tornará pública sua chave do canal, já que ficará visível no /whois dos bots.
Atualmente somente eventos Push são suportados.

KGB

O KGB suporta webhooks do gitlab. Para usar instâncias kgb fornecidas por dam, tina e gregoa a partir do salsa, defina um webhook em seu projeto:

http://kgb.debian.net:9418/webhook/?channel=<nome-do-canal-irc-sem-o-#>

Para detalhes, parâmetros adicionais e scripts de ajuda, veja a documentação do KGB em https://salsa.debian.org/kgb-team/kgb/wikis/usage

Lidando com o BTS do Debian a partir de mensagens de commit

Nós rodamos um receptor webhook que pode modificar o BTS do Debian baseado em mensagens de commit. Se quiser usá-lo, vá até seu projeto, "Configurações (Settings) → Webhooks" e adicione uma URL (veja abaixo), e clique em gravar. Nenhum token secreto é necessário, e atualmente ele somente lida com eventos push.

URLs possíveis:

https://webhook.salsa.debian.org/close/NOME-DO-FONTE
https://webhook.salsa.debian.org/tagpending/NOME-DO-FONTE

Substitua NOME-DO-FONTE com o nome de seu pacote-fonte e escolha entre close (fechar) ou tag pending (pendência de etiqueta), dependendo da ação que queira obter.

Você pode ignorar um branch ou padrão, digamos wip/*, ao fornecer o parâmetro ignored-namespaces (espaços de nome ignorados). Veja o README no código para mais detalhes.

Código: https://salsa.debian.org/salsa/salsa-webhook.

Chaves de implementação

Para tarefas de automatização FIXME

Lançadores

O Salsa disponibiliza lançadores (runners) compartilhados para todos os projetos. Todos os trabalhos sem etiquetas mais específicas executam dentro de um contêiner Docker privilegiado em uma VM de uso único. Conexões de saída a partir de VMs de lançadores compartilhados são limitados a http & https.

Você também pode adicionar lançadores de grupo para seu grupo ou lançadores específicos, e configurá-los para seu projeto.

Arquivos de configuração e ferramentas são mantidas pela equipe SalsaCI.

Hospedagem de páginas web

O Gitlab oferece o recurso "Páginas Gitlab" (GitLab Pages), e ele está habilitado no Salsa como https://<espaço-de-nome>.pages.debian.net/<projeto>

Esta funcionalidade faz uso do Gitlab-CI para gerar páginas estáticas em um diretório public, em cada push.

Veja a documentação oficial para detalhes. Note que hospedar páginas em domínios arbitrários - mesmo que suportado no desenvolvimento original upstream — não é suportado no Salsa devido à falta de largura de banda dentro do DSA para suportar este recurso (veja RT #7045).

ChrisLamb criou vários banners em formato de fita no estilo Github, "fork me on Salsa" que você pode adicionar aos seu site.

https://<espaço-de-nomes>.pages.debian.net deve funcionar, graças ao novo suporte a certificados curingas do Let's Encrypt.

Começando rapidamente

  1. Na página principal do seu projeto, use o botão Configure CI/CD (Set up CI/CD). (Se seu projeto estiver vazio, selecione Novo arquivo (New file) no lugar.)

  2. Escolha um modelo Gitlab CI Yaml (Gitlab CI Yaml template) (modelos Pages estão abaixo)

  3. Edite o modelo de forma a se ajustar ao que precisa, e salve-o
  4. Faça push de alguma coisa ao repositório. Você verá que existe um trabalho CI (CI Job) pendente
  5. Aguarde alguns minutos para que o trabalho execute. Quando estiver em Passado (Passed), você poderá ver sua página em https://<espaço-de-nomes>.pages.debian.net/<projeto>/)

Mesmo que futuramente planejemos suporte a geradores de páginas simples como Jekyll ou Hugo, na maior parte dos casos você deverá se conter ao modelo HTML e gerar páginas localmente ao realizar push, de modo a economizar os recursos no lançador. Alguns modelos podem requerer comandos não disponíveis no servidor.

Queremos reforçar isso. De verdade. Seja legal com o servidor. ;)

importante: (ao menos para a implementação de páginas estáticas) seus artefatos devem ser armazenados em um diretório chamado public/; se estiverem em um local diferente, use a seção script em .gitlab-ci.yml para criar esse diretório e copie o conteúdo ali.

Obtendo ajuda

Veja a descrição em manutenção do Salsa.

Dicas para usuários(as) anteriores do Alioth

Veja Migração do Alioth.

Boas práticas para uso de API

  • se quiser saber se um projeto existe, acesse o projeto pelo nome, autenticado; se obter um 404, então ele não existe.
  • não pesquise para obter uma identificação. Se precisar do id, acesso o projeto pelo nome e use path-encoding https://docs.gitlab.com/ee/api/#namespaced-path-encoding

  • não requisite todos os projetos em um grupo, a menos que realmente os queira. Se você realmente quer a lista, use simple=true (https://docs.gitlab.com/ee/api/groups.html#list-a-group-s-projects).

  • implemente paginação adequada, por favor não solicite simplesmente uma centena de elementos por página
  • defina um cabeçalho User-Agent com informações sobre o projeto; não faça requisições com cabeçalhos user agent genéricos

  • se usar uma lib (biblioteca), assegure-se de que a lib implemente a api corretamente
  • não execute trabalhos extensivos muito frequentemente
  • por favor considere usar vcswatch ou outros projetos de reunião de dados
  • não faça sondagens (polls) regularmente
  • se em dúvida, fala conosco antes de codificar, e fala conosco antes de colocar seu código em produção

Chaves de host SSH

Ao conectar com o Salsa para solicitar ou enviar ao repositório Git pela primeira vez, é essencial verificar as chaves ssh da máquina. As chaves para o Salsa foram publicadas como registros SSHFP DNS e também como o arquivo known_hosts do Debian. É uma operação feita uma única vez. De agora em diante, o ssh confiará as chaves no arquivo known_hosts local.


CategoryDeveloper