> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/referencia-da-api/version-support-agreement.md). # Contrato de Suporte de Versão Contrato de suporte de versão Este documento descreve a política de versionamento aplicada tanto ao Scene Editor no Creator Hub como ao framework de scripting (o `@dcl/sdk` pacote). O objetivo desta política de versionamento é estabelecer um contrato entre a equipa de SDK da Fundação Decentraland e os criadores de conteúdo, para definir expectativas claras e permitir que os criadores de conteúdo planeiem o seu trabalho em conformidade. ## Definições * *Número da versão* -- um identificador único para uma versão de software disponível publicamente. Este identificador consiste num *versão principal* número e um *versão secundária* número, separados por pontos (por exemplo, 7.2). * *Família de versões* -- todas as versões que têm a mesma versão principal formam uma família. Chamamos a versão A de *sucessora* da versão B se A e B pertencerem à mesma família e o número da versão secundária de A for superior ao de B (por exemplo, 7.11 é uma sucessora de 7.10). * *Breaking change* -- uma alteração que obriga um utilizador a alterar o seu código ou ativos para os manter a funcionar. Por exemplo, uma propriedade muda de nome e obriga o utilizador a alterar esse nome de propriedade sempre que é usado em todo o seu código. * *Non-breaking change* -- uma alteração que não requer qualquer ação por parte de um utilizador. O comportamento e as propriedades do código e dos ativos do utilizador permanecem inalterados. * *Versão estável* -- uma versão que proíbe breaking changes em todos os seus sucessores (que também são todos considerados estáveis). Qualquer breaking change deve ser introduzida apenas através da criação de uma nova família de versões, incrementando o número da versão principal; no entanto, veja a ressalva na secção de [breaking changes](#breaking-changes) secção. As Non-breaking changes são refletidas através do incremento do número da versão secundária. * *Versão instável* -- uma versão que permite breaking changes nas suas sucessoras. As breaking changes podem ser introduzidas através do incremento do número da versão secundária. ## Política de suporte Em cada família de versões estável, a Fundação Decentraland suporta apenas a versão secundária mais recente. Em qualquer momento, devem existir no máximo duas famílias suportadas. Por exemplo, se a versão secundária mais recente da família 6.x for 6.11, e a versão secundária mais recente da família 7.x for 7.3, espera-se que os criadores de conteúdo desenvolvam as suas scenes em 6.11 ou 7.3. As scenes que foram desenvolvidas e publicadas com a versão 6.10 ou anterior provavelmente continuarão a funcionar e os jogadores poderão desfrutá-las. No entanto, se essas scenes mais antigas tiverem algum problema, primeiro devem ser atualizadas para uma versão suportada, e o problema só será investigado se continuar a ocorrer numa versão suportada. O Scene Editor atualiza automaticamente o package de scripting de todas as scenes dentro da mesma família de versões, para que todos os programadores usem a versão suportada mais recente ao desenvolverem as suas scenes. ## Desenvolvimento de funcionalidades As novas funcionalidades serão lançadas apenas na versão mais recente em desenvolvimento. Assim que a equipa de desenvolvimento iniciar trabalho numa nova família de versões, as famílias de versões anteriores que permaneçam em suporte receberão apenas correções importantes de bugs e não serão implementadas funcionalidades adicionais. ## Breaking changes As breaking changes só deverão ocorrer em lançamentos principais. Não deverá haver breaking changes dentro dos lançamentos secundários estáveis da mesma família de versões, exceto em caso de emergência quando não existirem outros meios para o resolver. As breaking changes dentro de um lançamento secundário são uma medida drástica que os programadores evitarão a todo o custo. Os novos lançamentos secundários alargarão as capacidades da sintaxe existente, mas nunca deverão mudar aquilo que a sintaxe estabelecida produz, exceto quando corrigirem bugs. ### Alterações isoladas Em ocasiões muito raras, pode ser preferível fazer uma pequena alteração breaking isolada se isso só incomodar um pequeno subconjunto de utilizadores. (Criar uma nova versão principal incomoda todos os utilizadores.) Neste caso, o SDK pode descontinuar uma funcionalidade, mas deve continuar a suportá-la durante um período de tempo razoável. ### Alterações de emergência Em certos casos excecionais, como preocupações de segurança ou requisitos regulamentares, qualquer funcionalidade pode ser alterada de forma breaking, independentemente do seu nível de estabilidade, e não é prometida qualquer descontinuação nestas situações. ## Lançamentos estáveis e instáveis ### Alpha Sempre que é introduzido um novo lançamento principal, alguns lançamentos secundários iniciais podem ser rotulados como instáveis **alpha** versões. As breaking changes devem ser permitidas e esperadas em lançamentos alpha, e os utilizadores não devem ter qualquer expectativa de estabilidade. Os programadores são livres de experimentar com estas versões alpha, mas não é recomendável publicar conteúdo criado com versões alpha instáveis, pois não há garantia de que o conteúdo continuará a funcionar após alterações subsequentes. Também não é recomendável iniciar migrações grandes e complexas nesta fase, uma vez que poderão ser necessárias mais alterações antes do próximo lançamento estável. ### Beta Quando uma família de versões atinge um certo nível de maturidade, um **beta** lançamento é disponibilizado. Um lançamento beta é considerado completo e pronto para ser declarado estável, sujeito a testes públicos. As famílias de versões beta devem ser tão estáveis quanto possível; no entanto, é permitido que mudem ao longo do tempo. Estas alterações devem ser mínimas, mas podem incluir breaking changes. As breaking changes só podem ser introduzidas após um período razoável de descontinuação, para dar aos criadores de conteúdo a oportunidade de migrar as suas scenes. Este período de descontinuação deve ser definido quando a breaking change é introduzida. As famílias de versões beta devem estar em beta apenas durante um período de tempo limitado, especificado no momento em que são marcadas como beta. Devem ser promovidas a estáveis se não forem encontrados problemas nesse período. A duração desse período pode variar caso a caso, mas uma boa regra geral é 90 dias. O conteúdo escrito com a sintaxe de uma versão beta deve ser fácil de migrar para versões posteriores dentro dessa família. Ainda não é aconselhável desenvolver conteúdo para eventos importantes com uma versão beta, uma vez que os testes ainda estão em curso e é provável que existam bugs. ### Estável Quando o período beta termina sem problemas significativos, a família de versões é considerada **estável** e não deverá haver mais alterações à sintaxe, para além da adição de novas funcionalidades. A partir deste ponto, a versão é considerada a opção recomendada e incentivada para todos os programadores utilizarem. Uma família de versões estável deve ser totalmente suportada ao longo do seu ciclo de vida. Não pode haver breaking changes, sujeitas às ressalvas descritas abaixo. ## Funcionalidades instáveis em lançamentos estáveis Funcionalidades específicas num lançamento podem ter níveis de estabilidade diferentes do lançamento no seu conjunto. Isto pode acontecer porque a funcionalidade foi introduzida recentemente e requer mais testes, ou porque está destinada a ser substituída em breve. Por exemplo, um novo tipo de componente poderia ser introduzido como alpha num lançamento já estável do framework do SDK, uma vez que este componente em particular pode ainda exigir o seu próprio ciclo de testes. Pode então seguir o fluxo de versionamento descrito acima, passando de alpha para beta e depois para stable. Qualquer funcionalidade de um lançamento estável que não seja considerada estável deve ser claramente assinalada como tal na documentação. Os criadores que utilizem funcionalidades instáveis devem estar cientes de que a funcionalidade pode potencialmente sofrer breaking changes. Quaisquer breaking changes serão comunicadas de forma clara, incluindo guias de migração, e haverá um período de transição para que os criadores ajustem o código da sua scene. ## Durante quanto tempo suportamos uma família de versões estável? Quando uma nova família de versões se torna estável (7.x), a equipa compromete-se a suportar (correções importantes de erros) a versão anterior (6.x) durante vários meses, para dar aos criadores bastante tempo para migrarem. A duração é determinada caso a caso, dependendo do esforço de migração necessário. ## Versões pré-lançadas É sempre possível aceder às adições mais recentes ao framework de scripting instalando a `@next` versão do `@dcl/sdk` package numa scene. As funcionalidades neste branch podem ser instáveis ou não documentadas, uma vez que não são disponibilizadas como parte de uma versão oficialmente suportada do SDK. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/referencia-da-api/version-support-agreement.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.