Formas de versão de sua API, Parte 2.
Esta é parte dois de uma série no controle de versão da API. A Parte Um abrangia os métodos prevalecentes para a versão de sua API e permitindo que os clientes codificassem em uma versão especificamente. Eu sugiro que você leia essa publicação (pelo menos descreva a introdução!) Antes disso, pois fornece algum contexto necessário. Nele, sugeri um outro método que utiliza alguns conceitos pouco conhecidos das especificações do cabeçalho de Aceitação, que pode permitir que você faça uma API sem versão. Eu admitirei bem na frente, no entanto, é um pouco equivocado, mas acho que é importante. Você ainda pode editar as coisas na API, mas você não pode controlar a própria interface. Você está simplesmente a controlar as representações de recursos.
A alteração mais comum em qualquer API REST arquitetada é adicionar, alterar ou remover campos dos recursos. Novas informações são adicionadas ou podem estar em um formato diferente. As informações podem ficar indisponíveis. Você também pode adicionar, mover ou remover recursos. Dependendo da sua arquitetura API, os verbos HTTP podem significar coisas ligeiramente diferentes. Todos esses normalmente exigiriam um incremento da versão da API se eles causassem que os aplicativos existentes se quebrassem. Com um pouco de previsão, no entanto, sua API pode mudar sem exigir uma estratégia de controle de API completa.
Arquiteto uma interface sem versão:
Use esquemas de URI sãos: / api / collection_name / resource_id Siga as definições de métodos HTTP A adição de recursos deve sempre ser compatível com versões anteriores A remoção de recursos deveria ser feita através de versões de qualquer maneira. Os recursos móveis podem ser gerenciados por redirecionar códigos HTTP.
Representações de recursos de versão:
Use o cabeçalho de Aceitação A adição de informações deve sempre ser compatível com versões anteriores. A remoção de informações teria que ser feita através de versões de qualquer maneira. As informações de mudança podem ser feitas com Aceitação de versão.
Arquitetando uma API sem versão.
Deixe-me começar por dizer que eu reconheço que uma API sem versão é um pouco de um estado ideal, e uma API com uma estratégia de controle de versões bem pensada é muito preferível a uma API com uma tentativa mal pensada de não versão. Não há vergonha em dizer que você acha que precisa do controle de versão, nem que todas as APIs possíveis se encaixam nessa estratégia sem versão. Isso realmente funciona apenas para as APIs baseadas em manipulação de recursos com REST, que se seguem aos padrões vigentes. Dito isto, uma grande quantidade de APIs pode ser retrabalhada para se encaixar nesse estilo. Além disso, isso é destinado a APIs back-end, e não interfaces de interface com seu front-end na web. Na minha opinião, estas devem ser quase sempre APIs separadas para que você possa atualizar a funcionalidade de front-end da Web em seu próprio ritmo sem se preocupar com nenhum usuário da API. Eu sei que eu pessoalmente sou muito mais relaxado no meu seguimento de padrões para APIs front-end.
O primeiro passo para entender como criar uma API sem versão é saber que você não deseja versão da própria interface. Isso significa que você não quer mudar como e onde as informações são armazenadas e acessadas. Em termos práticos, esta é a estrutura URI. Mesmo esta regra pode ser dobrada, é claro - construída diretamente na especificação HTTP são redirecionamentos! Se você moviu informações, simplesmente forneça um redirecionamento permanente para o novo URI. Agora, o que acontece se você remover um recurso?
Os dois motivos por que um URI particular pode ser removido de uma API típica: ou o próprio tipo de recurso foi removido, ou mais comumente, que a representação particular do recurso não é mais suportada. No último caso, você realmente não aderiu à arquitetura REST: a representação do recurso deve ser desacoplada do URI. No caso anterior, se o tipo de recurso inteiro já não estiver acessível, é provavelmente por uma razão comercial, caso em que você deseja removê-lo de todas as versões anteriores da API também. Nesse caso, o controle de versão não conseguiu realmente nada, não é?
Adicionar recursos, ou informações aos recursos, sempre deve ser uma mudança compatível com versões anteriores. Se você estiver usando o JSON, adicionar elementos aos recursos existentes deve ser uma brisa. Mesmo que você tenha um esquema XML, você pode simplesmente adicioná-los ao esquema definido e alertar os clientes que podem ter baixado sua própria cópia do esquema para atualizá-lo. Se você quiser adicionar um recurso totalmente novo, basta adicioná-lo! Ninguém deve ser afetado.
Provavelmente, a coisa mais difícil de fazer versões sem alterações é o que acontece quando você executa um método específico em uma determinada API. Por exemplo, se você pudesse POST para / api / foo / e crie um novo recurso foo para você, mas agora você deseja que ele edite um recurso foo existente. O melhor que posso dizer é que não, em vez disso, siga as definições recomendadas do método de especificação HTTP explicitamente:
GET / api / foo / ou GET / api / foo / 1 recupera recursos ou recursos e é idempotente (repetitivo com os mesmos resultados) POST / api / foo / cria novos recursos e NÃO é idempotente (a repetição cria mais recursos) PUT / api / foo / 1 atualiza ou cria um recurso específico inteiro e são campos de atualizações idempotentes PATCH / api / foo / 1 (padrão proposto) de um recurso específico e é idempotente DELETE / api / foo / 1 exclui um recurso (às vezes coleções de recursos) e é idempotente.
Tecnicamente, acho que o DELETE deve notificar de alguma forma se o recurso não existisse em primeiro lugar e uma maneira apropriada de fazer isso seria um erro, mas eu vou adiar nisso. OPTIONS e HEAD são usados menos e se você estiver usando eles, você provavelmente sabe o que você está fazendo de qualquer maneira. Se você estiver usando PATCH, esteja ciente de que não é um padrão bem suportado, e muitas API aceitarão pedidos PUT incompletos e somente atualizarão os campos alterados. Eu acho que isso está bem, desde que seja um comportamento bem compreensivo e documentado, com suporte PATCH manchado, pelo menos até que seja mais aceitável.
Muitas vezes, os recursos são modificados pelos pedidos POST. Um formulário envia, você interpreta os dados e muda um recurso. Este é um padrão comum em APIs de front-end, e como eu mencionei acima, isso é bom. Não é perfeito, mas bom. Em uma API de back-end, isso não deve acontecer! Use uma solicitação PUT ou PATCH e defina explicitamente o que deseja que o novo recurso seja. Uma desculpa comum é as versões antigas do IE don & # 8217; t suporte PUT ou PATCH, mas esta é uma API de back-end, ela é boa! Todas as principais bibliotecas que conheço pelo menos suportam PUT - se você estiver usando um que não tenha, provavelmente você deve procurar em outro lugar.
Em suma, um pré-requisito para a inexatidão é que todos os recursos que você deve poder ser acessados e manipulados em um fasion consistente, sendo as únicas diretivas o URI para o recurso, o método HTTP e os dados que representam o próprio recurso. Se você estiver manipulando um único recurso lógico - digamos, um perfil de usuário - de várias URIs, você provavelmente encontrará situações em que você precisa para a versão.
Versão de representações de recursos.
Como mencionei na introdução, as próprias representações de recursos transferidas para o cliente podem e provavelmente devem ser controladas. A beleza desta abordagem é que cada recurso pode ser versionado de forma independente. Se você mudar um recurso, um mês depois, você decide mudar um recurso diferente, você não precisará aumentar um contador de versão da API duas vezes. Cada versão do recurso é incrementada individualmente. Note-se que não estou falando sobre a versão dos próprios recursos, apenas a representação do recurso. Se você tiver um recurso versionado, por exemplo, um documento que tenha revisões anteriores disponíveis, estes devem ser acessados separadamente do método I & # 8217; descrevendo aqui.
Familiarizar-se com a especificação de cabeçalho Accept provavelmente irá ajudá-lo a entender a verdadeira profundidade de quão longe as especificações podem ir para a prova de futuro. Quase todo mundo sabe que o cabeçalho Aceita especifica o tipo de MIME-Type que o solicitante espera, como application / json. Menos sabe que não pode apenas especificar um tipo, mas pode especificar vários tipos aceitáveis, bem como parâmetros em cada tipo. Para representar recursos de versão, nós iremos aproveitar os parâmetros de tipo.
I & # 8217; ll entrar e você considerou o seguinte:
Mesmo sem entender completamente o cabeçalho Aceites, você provavelmente pode adivinhar que essa seqüência de caracteres implica que ela espera que o aplicativo / vnd. example. foo digite o formato json, a versão 2, se disponível, e qualquer versão do contrário. Analisar o cabeçalho Aceitar de uma maneira consistente com as especificações pode ser difícil apenas porque muitas bibliotecas não analisam a caixa.
Então, quando você deve representar recursos de versão? Como mencionei acima, se você estiver removendo informações sobre um recurso, é provavelmente por uma razão comercial que você não quer mais exposto. Na era da transmissão comprimida de hoje, há pouco ganho para tirar da informação simplesmente porque você não sente mais útil. A adição de informações sempre deve ser possível de forma compatível com versões anteriores. Você pode querer versão em caso de alterar o nome e / ou o tipo de um campo, por exemplo, se você quiser (tempo de exemplo do mundo real!), Repurpose um campo booleano com o & # 8220; habilitado & # 8221; para um status mais genérico & # 8220; & # 8221; tipo de enum.
Agora, como faço isso?
Infelizmente, muito do que eu discuti aqui tem pouco ou nenhum suporte amplo na comunidade de pessoas que realmente criam API amplamente utilizadas. Eu suspeito que nenhuma parte pequena disso é devido à dificuldade em implementá-los em uma aplicação do mundo real. Dependendo da sua plataforma, pode ser fácil ou difícil, e poucas bibliotecas suportarão uma estratégia de controle como esta fora da caixa. O mais próximo que eu sei é o nó de resposição que suporta roteamento versionado com base em um cabeçalho de versão de aceitação.
Eu irei a passar por algumas bibliotecas e tentando estendê-las para suportar o controle de versão no futuro. Possivelmente tentando minha própria biblioteca que assa muito isso gratuitamente. Quanto mais fácil é para um desenvolvedor escrever código compatível com padrões, mais provável eles vão adotá-lo, porque, no final, se se resume à facilidade de desenvolvimento versus adesão aos padrões, acho que todos sabemos que a facilidade ganhará a cada vez .
Seu Centro de conhecimento de gerenciamento de documentos.
Controle de Documentos: As Estratégias e Táticas que o Fazem Tick.
Publicado por Jana Wiggins em 3 de dezembro de 2018 8:30:00 AM.
Quando se trata dos documentos da sua organização, você simplesmente não pode confiar em armazenar e compartilhar. Esses documentos suportam suas operações comerciais e o cumprimento das normas governamentais. Eles são seus arquivos de pessoal críticos e comunicações com membros da equipe, parceiros e clientes. Você precisa ir além de armazenar e compartilhar: estas táticas de nádegas simplesmente não cortam mais isso em nosso mundo saturado de informações. O que a sua organização precisa é o controle de documentos através de um poderoso software de gerenciamento de documentos.
O software de controle de documentos não só agiliza os processos e limpa as comunicações, mas também torna o ambiente de trabalho muito mais agradável para sua equipe. Quando eles se sentem organizados e produtivos, eles se sentem bem com seu trabalho.
Aqui estão as estratégias de alto nível e as táticas acionáveis que você precisa colocar em jogo ao gerenciar o controle de documentos com uma solução de software eficaz.
INICIE COM AS ESTRATÉGIAS:
Mantenha um registro de cada documento. O controle adequado da versão do documento inclui todo o histórico de versões do documento. Desta forma, seu sistema e equipe não estão sobrecarregados com vários registros para cada nova versão.
Mantenha todos seguindo a mesma política. Quando todos os processos são consistentes, há muito menos risco de erro humano, documentos errados e falta de comunicação.
Não use pastas. Eles podem parecer uma ótima ferramenta para organizar sua informação, mas no final do dia, você é deixado a caça manualmente e documentos rotulados inconsistentemente. As pastas armazenam documentos, mas certamente não os controlam ou controlam.
SEGUIMENTO COM AS TÁCTICAS:
1. Mantenha o controle de versão simples.
Use uma solução de gerenciamento de documentos com funcionalidade de controle de versão de documento simples e transparente. Também deve ser adaptável a quaisquer mudanças operacionais - em outras palavras, o sistema evolui com sua organização. Lembre-se: você quer que sua equipe esteja totalmente a bordo com a solução. Se o software for um aborrecimento para operar, ou se já está desatualizado dentro de alguns meses, ninguém vai usá-lo.
2. Mantenha-o no radar.
Não é suficiente desenvolver uma política de gerenciamento de documentos. Esse é apenas o seu ponto de partida. Você deve acompanhar esta estratégia, fazendo com que seu uso faça parte das revisões de desempenho de todos. Quando as pessoas estão motivadas a usar o sistema - quando o sistema está alinhado com as metas e objetivos do local de trabalho - eles estarão muito mais inclinados a usá-lo efetivamente.
É aí que as pastas definitivamente perdem o brilho quando se trata de controle abrangente e transparente de documentos. Implementar um sistema de gerenciamento de documentos eletrônico que gerencie documentos e registros com metadados. Desta forma, os documentos e registros eletrônicos são atribuídos a um índice (ou seja, metadados) para armazenamento e recuperação rápidos e fáceis.
Os benefícios de gerenciamento de documentos sem problemas e controle de versão eficiente são aplicáveis a todas as indústrias e organizações, mas são especialmente relevantes para agências de marketing. Clique abaixo para baixar nosso relatório gratuito: 8 estratégias de gerenciamento de ativos de marketing que sua agência precisa saber.
Inscreva-se por Email & amp; Não perca nossa newsletter!
Conecte-se conosco.
Postagens recentes.
Contate-Nos.
© 2018 Document Advantage Corporation.
Fornecedor de soluções de gerenciamento de documentos eletrônicos baseados em Tampa, Florida, especializado em gerenciamento de documentos, automação de processos de negócios e gerenciamento de registros.
Versão semântica 2.0.0.
Dado um número de versão MAJOR. MINOR. PATCH, incremente:
MAJOR versão quando você faz alterações de API incompatíveis, versão MENOR quando você adiciona funcionalidade de forma compatível com versões anteriores e versão PATCH quando você faz correções de bugs compatíveis com versões anteriores.
Etiquetas adicionais para pré-lançamento e metadados de compilação estão disponíveis como extensões ao formato MAJOR. MINOR. PATCH.
Introdução.
No mundo do gerenciamento de software, existe um lugar de medo chamado "dependência do inferno". Quanto maior o seu sistema e quanto mais pacotes você integra no seu software, mais provável é encontrar-se, um dia, neste poço de desespero.
Em sistemas com muitas dependências, lançar novas versões de pacotes pode rapidamente se tornar um pesadelo. Se as especificações de dependência forem muito apertadas, você corre o risco de bloqueio de versão (a incapacidade de atualizar um pacote sem ter que liberar novas versões de cada pacote dependente). Se as dependências são especificadas de forma muito frouxa, você será inevitavelmente mordido pela versão promiscuidade (assumindo a compatibilidade com mais versões futuras do que o razoável). O inferno de dependência é onde você está quando o bloqueio de versão e / ou a promiscuidade da versão impedem que você transmita com facilidade e segurança seu projeto.
Como solução para este problema, proponho um conjunto simples de regras e requisitos que determinam como os números de versão são atribuídos e incrementados. Essas regras são baseadas, mas não necessariamente limitadas, a práticas comuns difundidas pré-existentes em uso em software aberto e de código aberto. Para que este sistema funcione, primeiro você precisa declarar uma API pública. Isso pode consistir em documentação ou ser aplicado pelo próprio código. Independentemente disso, é importante que esta API seja clara e precisa. Uma vez que você identifica sua API pública, você comunica suas alterações com incrementos específicos ao seu número de versão. Considere um formato de versão de X. Y.Z (Major. Minor. Patch). Correção de erros que não afetam o incremento da API na versão do patch, as adições / alterações da API compatíveis com versões anteriores incrementam a versão menor, e as mudanças de API incompatíveis com a frente incrementam a versão principal.
Eu chamo esse sistema de "Versão semântica". Sob este esquema, os números de versão e a forma como eles mudam transmitem significado sobre o código subjacente e o que foi modificado de uma versão para a próxima.
Especificação de versão semântica (SemVer)
As palavras-chave "DEVE", "NÃO DEVEM", "REQUERIDO", "NÃO", "DEVEM", "NÃO DEVEM", "RECOMENDADO", "MAYO" e "OPCIONAL" neste documento são para ser interpretado como descrito na RFC 2119.
O software que usa a versão semântica DEVE declarar uma API pública. Esta API pode ser declarada no próprio código ou existir estritamente na documentação. No entanto, é feito, deve ser preciso e abrangente.
Um número de versão normal DEVE tomar a forma X. Y.Z onde X, Y e Z são números inteiros não negativos e NÃO DEVEM CONNECER ZONES PRINCIPAIS. X é a versão principal, Y é a versão menor e Z é a versão do patch. Cada elemento DEVE aumentar numericamente. Por exemplo: 1.9.0 - & gt; 1.10.0 - & gt; 1.11.0.
Uma vez que um pacote versionado foi lançado, o conteúdo dessa versão NÃO DEVE ser modificado. Todas as modificações DEVEM ser lançadas como uma nova versão.
A versão principal zero (0.y. z) é para desenvolvimento inicial. Qualquer coisa pode mudar a qualquer momento. A API pública não deve ser considerada estável.
A versão 1.0.0 define a API pública. A forma como o número da versão é incrementada após esta versão é dependente desta API pública e como ela muda.
A versão de patch Z (x. y.Z | x & gt; 0) DEVE ser incrementada se apenas as correções de erros compatíveis com versões anteriores forem introduzidas. Uma correção de erro é definida como uma alteração interna que corrige o comportamento incorreto.
A versão menor Y (x. Y.z | x & gt; 0) DEVE ser incrementada se a nova funcionalidade compatível com versões anteriores for introduzida na API pública. DEVE ser incrementado se qualquer funcionalidade pública da API estiver marcada como obsoleta. PODE ser incrementado se novas funcionalidades ou melhorias forem introduzidas dentro do código privado. PODE incluir mudanças no nível do patch. A versão do patch DEVE ser redefinida para 0 quando a versão menor for incrementada.
A versão principal X (X. y.z | X & gt; 0) DEVE ser incrementada se alguma alteração incompatível com versões anteriores for introduzida na API pública. PODE incluir mudanças menores e de nível de patch. Patch e versão menor DEVEM ser redefinir para 0 quando a versão principal é incrementada.
Uma versão pré-lançamento pode ser denotada anexando um hífen e uma série de identificadores separados por pontos imediatamente após a versão do patch. Os identificadores DEVEM compreender apenas alfanuméricos ASCII e hífen [0-9A-Za-z-]. Identificadores NÃO DEVEM estar vazios. Os identificadores numéricos NÃO DEVEM incluir os zeros iniciais. As versões pré-lançamento têm uma precedência menor do que a versão normal associada. Uma versão pré-lançamento indica que a versão é instável e pode não satisfazer os requisitos de compatibilidade pretendidos conforme indicado pela versão normal associada. Exemplos: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.0-0.3.7, 1.0.0-x.7.z.92.
Os metadados de compilação podem ser denotados anexando um sinal de mais e uma série de identificadores separados por pontos imediatamente após o patch ou a versão pré-lançamento. Os identificadores DEVEM compreender apenas alfanuméricos ASCII e hífen [0-9A-Za-z-]. Identificadores NÃO DEVEM estar vazios. Construir metadados DEVE ser ignorado ao determinar a precedência da versão. Assim, duas versões que diferem apenas nos metadados de compilação, têm a mesma precedência. Exemplos: 1.0.0-alpha + 001, 1.0.0 + 20180313144700, 1.0.0-beta + exp. sha.5114f85.
A prioridade refere-se a como as versões são comparadas entre si quando encomendadas. A prioridade DEVE ser calculada separando a versão em identificadores maiores, menores, de patch e de pré-lançamento nessa ordem (os metadados de compilação não figuram em precedência). A prioridade é determinada pela primeira diferença ao comparar cada um desses identificadores da esquerda para a direita da seguinte maneira: as versões principais, menores e patch são sempre comparadas numericamente. Exemplo: 1.0.0 & lt; 2.0.0 & lt; 2.1.0 & lt; 2.1.1. Quando maior, menor e patch são iguais, uma versão pré-lançamento tem menor precedência do que uma versão normal. Exemplo: 1.0.0-alpha & lt; 1.0.0. A prioridade para duas versões de pré-lançamento com a mesma versão principal, menor e de patch DEVE ser determinada comparando cada identificador separado por pontos da esquerda para a direita até que uma diferença seja encontrada da seguinte forma: identificadores consistindo apenas de dígitos são comparados numericamente e identificadores com letras ou hifens são comparados lexicamente em ordem de classificação ASCII. Os identificadores numéricos sempre têm menor precedência do que os identificadores não-numéricos. Um conjunto maior de campos de pré-lançamento tem um precedente maior do que um conjunto menor, se todos os identificadores anteriores forem iguais. Exemplo: 1.0.0-alpha & lt; 1.0.0-alpha.1 & lt; 1.0.0-alpha. beta & lt; 1.0.0-beta & lt; 1.0.0-beta.2 & lt; 1.0.0-beta.11 & lt; 1.0.0-rc.1 & lt; 1.0.0.
Por que usar a versão semântica?
Esta não é uma ideia nova ou revolucionária. Na verdade, você provavelmente faz algo perto disso. O problema é que "fechar" não é suficientemente bom. Sem conformidade com algum tipo de especificação formal, os números de versão são essencialmente inúteis para o gerenciamento de dependências. Ao dar um nome e uma definição clara às ideias acima, torna-se fácil comunicar suas intenções aos usuários do seu software. Uma vez que essas intenções são claras, as especificações de dependência flexíveis (mas não muito flexíveis) podem finalmente ser feitas.
Um exemplo simples irá demonstrar como o Versioning Semântico pode tornar a dependência do inferno uma coisa do passado. Considere uma biblioteca chamada "Firetruck". Ela requer um pacote com versão semântica chamado "Escada". No momento em que o Firetruck é criado, a Ladder está na versão 3.1.0. Uma vez que o Firetruck usa algumas funcionalidades que foram introduzidas pela primeira vez em 3.1.0, você pode especificar com segurança a dependência da Escada como maior ou igual a 3.1.0, mas inferior a 4.0.0. Agora, quando a Ladder versão 3.1.1 e 3.2.0 estiverem disponíveis, você pode liberá-las para seu sistema de gerenciamento de pacotes e saber que elas serão compatíveis com o software dependente existente.
Como desenvolvedor responsável, você, obviamente, deseja verificar se as atualizações de pacotes funcionam como anunciadas. O mundo real é um lugar bagunçado; Não há nada que possamos fazer sobre isso, mas fique atento. O que você pode fazer é permitir que o Semantic Versioning forneça uma maneira sã de liberar e atualizar pacotes sem ter que rolar novas versões de pacotes dependentes, economizando tempo e dificuldade.
Se tudo isso parecer desejável, tudo o que você precisa fazer para começar a usar o Versioning Semântico é declarar que você está fazendo isso e depois seguir as regras. Ligue para este site a partir do seu README para que outros conheçam as regras e possam se beneficiar delas.
Como faço para lidar com revisões na fase de desenvolvimento inicial 0.y. z?
A coisa mais simples a fazer é iniciar sua versão de desenvolvimento inicial em 0.1.0 e, em seguida, incrementar a versão menor para cada versão subseqüente.
Como eu sei quando lançar 1.0.0?
Se o seu software estiver sendo usado na produção, provavelmente ele já deve ser 1.0.0. Se você tem uma API estável sobre a qual os usuários vieram a depender, você deve ser 1.0.0. Se você se preocupa muito com a compatibilidade com versões anteriores, provavelmente você já deve estar 1.0.0.
Isso não desencoraja o rápido desenvolvimento e a rápida iteração?
A versão principal zero é tudo sobre desenvolvimento rápido. Se você estiver alterando a API todos os dias, você ainda deve estar na versão 0.y. z ou em um ramo de desenvolvimento separado trabalhando na próxima versão principal.
Se mesmo as mais pequenas mudanças incompatíveis para trás para a API pública exigem um problema de versão principal, não acabarei na versão 42.0.0 muito rapidamente?
Esta é uma questão de desenvolvimento responsável e previsão. Alterações incompatíveis não devem ser introduzidas levemente em um software que tenha muitos códigos dependentes. O custo que deve ser incorrido para atualizar pode ser significativo. Ter que superar as principais versões para liberar mudanças incompatíveis significa que você pensará no impacto de suas mudanças e avaliará a relação custo / benefício envolvida.
Documentar toda a API pública é muito trabalho!
É sua responsabilidade como desenvolvedor profissional documentar adequadamente o software que é destinado a outros usuários. Gerenciando a complexidade do software é uma parte extremamente importante de manter um projeto eficiente, e isso é difícil de fazer se ninguém souber usar seu software ou quais métodos são seguros. A longo prazo, a versão semântica e a insistência em uma API pública bem definida podem manter todos e todos funcionando sem problemas.
O que eu faço se eu acidentalmente liberar uma mudança incompatível para trás como uma versão menor?
Assim que você perceber que você quebrou as especificações da Versão Semântica, corrija o problema e libere uma nova versão menor que corrija o problema e restaure a compatibilidade com versões anteriores. Mesmo nessa circunstância, é inaceitável modificar os lançamentos versionados. Se for apropriado, documentar a versão ofensiva e informar seus usuários do problema para que estejam cientes da versão ofensiva.
O que devo fazer se atualizar minhas próprias dependências sem alterar a API pública?
Isso seria considerado compatível, uma vez que não afeta a API pública. Software que depende explicitamente das mesmas dependências que o seu pacote deve ter suas próprias especificações de dependência e o autor notará quaisquer conflitos. Determinar se a alteração é um nível de patch ou modificação de nível menor depende se você atualizou suas dependências para corrigir um erro ou introduzir novas funcionalidades. Eu normalmente esperaria um código adicional para a última instância, caso em que é, obviamente, um incremento de nível menor.
E se eu alterar inadvertidamente a API pública de uma maneira que não é compatível com a alteração do número de versão (ou seja, o código introduz incorretamente uma grande mudança de quebra em uma versão de patch)?
Use seu melhor julgamento. Se você tiver um público enorme que será impactado drasticamente ao mudar o comportamento de volta ao que a API pública pretendia, então talvez seja melhor realizar uma versão de versão importante, mesmo que a correção possa ser considerada como uma versão de patch. Lembre-se, o Versioning Semântico é sobre transmitir o significado pelo modo como o número da versão muda. Se essas mudanças forem importantes para seus usuários, use o número da versão para informá-las.
Como devo lidar com a funcionalidade de desaprovação?
Descartar a funcionalidade existente é uma parte normal do desenvolvimento de software e muitas vezes é necessário para avançar o progresso. Quando você deprecia parte de sua API pública, você deve fazer duas coisas: (1) atualize sua documentação para que os usuários saibam sobre a mudança, (2) emita uma nova versão menor com a desaprovação no lugar. Antes de remover completamente a funcionalidade em uma nova versão principal, deve haver pelo menos uma versão menor que contenha a desaprovação para que os usuários possam transição suave para a nova API.
Semver tem um limite de tamanho na seqüência de versão?
Não, mas use um bom julgamento. Uma string de versão de 255 caracteres provavelmente é um exagero, por exemplo. Além disso, sistemas específicos podem impor seus próprios limites ao tamanho da string.
A especificação da versão semântica é de autoria de Tom Preston-Werner, inventor de Gravatars e co-fundador da GitHub.
Se você quiser deixar comentários, abra um problema no GitHub.
No comments:
Post a Comment