You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# Package evolution - changing stuff in your package {#evolution}
6
+
# Evolução do pacote - alteração de itens em seu pacote {#evolution}
7
7
8
8
```{block, type="summaryblock"}
9
-
This chapter presents our guidance for changing stuff in your package: changing parameter names, changing function names, deprecating functions, and even retiring and archiving packages.
9
+
Este capítulo apresenta nossa orientação para alterar coisas em seu pacote: alterar nomes de parâmetros, alterar nomes de funções, depreciar funções e até mesmo retirar e arquivar pacotes.
10
10
11
-
_This chapter was initially contributed as a tech note on rOpenSci website by [Scott Chamberlain](https://github.com/sckott); you can read the original version [here](https://ropensci.org/technotes/2017/01/05/package-evolution/)._
11
+
_Este capítulo foi inicialmente contribuído como uma nota técnica no site da rOpenSci por [Scott Chamberlain](https://github.com/sckott); você pode ler a versão original [aqui] (https://ropensci.org/technotes/2017/01/05/package-evolution/)._
12
12
```
13
13
14
-
## Philosophy of changes {#philosophy-of-changes}
14
+
## Filosofia das alterações {#philosophy-of-changes}
15
15
16
-
Everyone's free to have their own opinion about how freely parameters/functions/etc. are changed in a library - rules about package changes are not enforced by CRAN or otherwise. Generally, as a library gets more mature, changes to user facing methods (i.e., exported functions in an R package) should become very rare. Libraries that are dependencies of many other libraries are likely to be more careful about changes, and should be.
16
+
Todos são livres para ter sua própria opinião sobre a liberdade com que parâmetros/funções/etc. são alterados em uma biblioteca - as regras sobre alterações de pacotes não são impostas pelo CRAN ou de outra forma. Em geral, à medida que uma biblioteca se torna mais madura, as alterações nos métodos voltados para o usuário (ou seja, funções exportadas em um pacote R) devem se tornar muito raras. As bibliotecas que são dependências de muitas outras bibliotecas provavelmente serão mais cuidadosas com as alterações, e devem ser.
17
17
18
-
## The lifecycle package {#the-lifecycle-package}
18
+
## O pacote de ciclo de vida {#the-lifecycle-package}
19
19
20
-
This chapter presents solutions that do not require the lifecycle package but you might still find it useful.
21
-
We recommend [reading the lifecycle documentation](https://lifecycle.r-lib.org/articles/stages.html).
20
+
Este capítulo apresenta soluções que não requerem o pacote lifecycle, mas que você ainda pode considerar úteis.
21
+
Recomendamos que você [que você leia a documentação do ciclo de vida](https://lifecycle.r-lib.org/articles/stages.html).
## Parâmetros: alteração dos nomes dos parâmetros {#parameters-changing-parameter-names}
24
24
25
-
Sometimes parameter names must be changed for clarity, or some other reason.
25
+
Às vezes, os nomes dos parâmetros precisam ser alterados para maior clareza ou por algum outro motivo.
26
26
27
-
A possible approach is check if deprecated arguments are not missing, and stop providing a meaningful message.
27
+
Uma abordagem possível é verificar se os argumentos obsoletos não estão faltando e parar de fornecer uma mensagem significativa.
28
28
29
29
```r
30
30
foo_bar<-function(x, y) {
@@ -38,7 +38,7 @@ foo_bar(x = 5)
38
38
#> Error in foo_bar(x = 5) : use 'y' instead of 'x'
39
39
```
40
40
41
-
If you want to be more helpful, you could emit a warning but automatically take the necessary action:
41
+
Se quiser ser mais útil, você pode emitir um aviso, mas tomar automaticamente a ação necessária:
42
42
43
43
```r
44
44
foo_bar<-function(x, y) {
@@ -53,21 +53,21 @@ foo_bar(x = 5)
53
53
#> 25
54
54
```
55
55
56
-
Be aware of the parameter `...`. If your function has`...`, and you have already removed a parameter (lets call it`z`), a user may have older code that uses `z`. When they pass in `z`, it's not a parameter in the function definition, and will likely be silently ignored -- not what you want. Instead, leave the argument around, throwing an error if it used.
56
+
Esteja ciente do parâmetro `...`. Se sua função tiver`...` e você já tiver removido um parâmetro (vamos chamá-lo de`z`), um usuário pode ter um código mais antigo que usa `z`. Quando você passa o parâmetro `z` ele não é um parâmetro na definição da função e provavelmente será ignorado silenciosamente - não é o que você deseja. Em vez disso, deixe o argumento por perto, lançando um erro se ele for usado.
57
57
58
-
## Functions: changing function names {#functions-changing-function-names}
58
+
## Funções: alteração de nomes de funções {#functions-changing-function-names}
59
59
60
-
If you must change a function name, do it gradually, as with any other change in your package.
60
+
Se você precisar alterar o nome de uma função, faça-o gradualmente, como em qualquer outra alteração em seu pacote.
61
61
62
-
Let's say you have a function`foo`.
62
+
Digamos que você tenha uma função`foo`.
63
63
64
64
```r
65
65
foo<-function(x) x+1
66
66
```
67
67
68
-
However, you want to change the function name to`bar`.
68
+
No entanto, você deseja alterar o nome da função para`bar`.
69
69
70
-
Instead of simply changing the function name and `foo`no longer existing straight away, in the first version of the package where`bar`appears, make an alias like:
70
+
Em vez de simplesmente alterar o nome da função e `foo`deixar de existir imediatamente, na primeira versão do pacote em que o`bar`aparecer, crie um alias como:
71
71
72
72
```r
73
73
#' foo - add 1 to an input
@@ -79,9 +79,9 @@ foo <- function(x) x + 1
79
79
bar<-foo
80
80
```
81
81
82
-
With the above solution, the user can use either `foo()`or`bar()` -- either will do the same thing, as they are the same function.
82
+
Com a solução acima, o usuário pode usar `foo()`ou`bar()` -- ambos farão a mesma coisa, pois são a mesma função.
83
83
84
-
It's also useful to have a message but then you'll only want to throw that message when they use the old function, e.g.,
84
+
Também é útil ter uma mensagem, mas você só vai querer lançar essa mensagem quando eles usarem a função antiga, por exemplo,
85
85
86
86
```r
87
87
#' foo - add 1 to an input
@@ -96,33 +96,33 @@ foo <- function(x) {
96
96
bar<-function(x) x+1
97
97
```
98
98
99
-
After users have used the package version for a while (with both `foo`and`bar`), in the next version you can remove the old function name (`foo`), and only have`bar`.
99
+
Depois que os usuários tiverem usado a versão do pacote por algum tempo (com ambos os `foo`e`bar`), na próxima versão você poderá remover o nome da função antiga (`foo`), e você terá apenas`bar`.
## Funções: depreciadas e extintas {#functions-deprecate-defunct}
108
108
109
-
To remove a function from a package (let's say your package name is `helloworld`), you can use the following protocol:
109
+
Para remover uma função de um pacote (digamos que o nome do seu pacote seja `helloworld`), você pode usar o seguinte protocolo:
110
110
111
-
-Mark the function as deprecated in package version `x` (e.g., `v0.2.0`)
111
+
-Marque a função como obsoleta na versão do pacote `x` (por exemplo, `v0.2.0`)
112
112
113
-
In the function itself, use `.Deprecated()`to point to the replacement function:
113
+
Na própria função, use `.Deprecated()`para apontar para a função de substituição:
114
114
115
115
```r
116
116
foo<-function() {
117
117
.Deprecated("bar")
118
118
}
119
119
```
120
120
121
-
There's options in`.Deprecated`for specifying a new function name, as well as a new package name, which makes sense when moving functions into different packages.
121
+
Há opções em`.Deprecated`para especificar um novo nome de função, bem como um novo nome de pacote, o que faz sentido quando você move funções para pacotes diferentes.
122
122
123
-
The message that's given by `.Deprecated`is a warning, so can be suppressed by users with`suppressWarnings()`if desired.
123
+
A mensagem que é dada por `.Deprecated`é um aviso, portanto, pode ser suprimida por usuários com`suppressWarnings()`se você desejar.
124
124
125
-
Make a man page for deprecated functions like:
125
+
Crie uma página de manual para funções obsoletas, como:
126
126
127
127
```r
128
128
#' Deprecated functions in helloworld
@@ -138,43 +138,43 @@ Make a man page for deprecated functions like:
138
138
NULL
139
139
```
140
140
141
-
This creates a man page that users can access like ``?`helloworld-deprecated` ``and they'll see in the documentation index. Add any functions to this page as needed, and take away as a function moves to defunct (see below).
141
+
Isso cria uma página de manual que os usuários podem acessar como ``?`helloworld-deprecated` ``e que você verá no índice da documentação. Adicione quaisquer funções a essa página conforme necessário e remova-as quando uma função se tornar obsoleta (veja abaixo).
142
142
143
-
-In the next version (`v0.3.0`) you can make the function defunct (that is, completely gone from the package, except for a man page with a note about it).
143
+
-Na próxima versão (`v0.3.0`), você pode tornar a função extinta (ou seja, completamente fora do pacote, exceto por uma página de manual com uma nota sobre ela).
144
144
145
-
In the function itself, use `.Defunct()`like:
145
+
Na própria função, use `.Defunct()`como:
146
146
147
147
```r
148
148
foo<-function() {
149
149
.Defunct("bar")
150
150
}
151
151
```
152
152
153
-
Note that the message in`.Defunct`is an error so that the function stops whereas`.Deprecated`uses a warning that let the function proceed.
153
+
Observe que a mensagem em`.Defunct`é um erro para que a função pare, enquanto`.Deprecated`usa um aviso que permite que a função continue.
154
154
155
-
In addition, it's good to add `...`to all defunct functions so that if users pass in any parameters they'll get the same defunct message instead of a `unused argument`message, so like:
155
+
Além disso, é bom adicionar `...`a todas as funções extintas para que, se os usuários passarem algum parâmetro, recebam a mesma mensagem de extinção em vez de um `unused argument`assim, por exemplo:
156
156
157
157
```r
158
158
foo<-function(...) {
159
159
.Defunct("bar")
160
160
}
161
161
```
162
162
163
-
Without`...`gives:
163
+
Sem`...`dá:
164
164
165
165
```r
166
166
foo(x=5)
167
167
#> Error in foo(x = 5) : unused argument (x = 5)
168
168
```
169
169
170
-
And with`...`gives:
170
+
E com`...`dá:
171
171
172
172
```r
173
173
foo(x=5)
174
174
#> Error: 'foo' has been removed from this package
175
175
```
176
176
177
-
Make a man page for defunct functions like:
177
+
Faça uma página de manual para funções extintas, como:
178
178
179
179
```r
180
180
#' Defunct functions in helloworld
@@ -189,21 +189,21 @@ Make a man page for defunct functions like:
189
189
NULL
190
190
```
191
191
192
-
This creates a man page that users can access like ``?`helloworld-defunct` ``and they'll see in the documentation index. Add any functions to this page as needed. You'll likely want to keep this man page indefinitely.
192
+
Isso cria uma página de manual que os usuários podem acessar como ``?`helloworld-defunct` ``e que você verá no índice da documentação. Você pode adicionar quaisquer funções a essa página, conforme necessário. Você provavelmente desejará manter essa página de manual indefinidamente.
### Teste de funções obsoletas {#testing-deprecated-functions}
195
195
196
-
You don't have to change the tests of deprecated functions until they are made defunct.
196
+
Você não precisa alterar os testes de funções obsoletas até que elas se tornem obsoletas.
197
197
198
-
-Consider any changes made to a deprecated function. Along with using`.Deprecated`inside the function, did you change the parameters at all in the deprecated function, or create a new function that replaces the deprecated function, etc. Those changes should be tested if any made.
199
-
-Related to above, if the deprecated function is simply getting a name change, perhaps test that the old and new functions return identical results.
200
-
-[`suppressWarnings()`could be used](https://community.rstudio.com/t/unit-testing-of-a-deprecated-function/42837/2)to suppress the warning thrown from`.Deprecated`, but tests are not user facing, so it is not that bad if the warning is thrown in tests, and the warning could even be used as a reminder to the maintainer.
198
+
-Considere todas as alterações feitas em uma função obsoleta. Além de usar`.Deprecated`dentro da função, você alterou os parâmetros na função obsoleta ou criou uma nova função que substitui a função obsoleta, etc.? Essas alterações devem ser testadas, caso você as tenha feito.
199
+
-Em relação ao que foi dito acima, se a função obsoleta estiver apenas recebendo uma alteração de nome, talvez você possa testar se as funções antiga e nova retornam resultados idênticos.
200
+
-[`suppressWarnings()`poderia ser usado](https://community.rstudio.com/t/unit-testing-of-a-deprecated-function/42837/2)para suprimir o aviso lançado pelo`.Deprecated` mas os testes não são voltados para o usuário, portanto, não é tão ruim se o aviso for lançado nos testes, e o aviso pode até ser usado como um lembrete para o mantenedor.
201
201
202
-
Once a function is made defunct, its tests are simply removed.
202
+
Quando uma função se torna extinta, seus testes são simplesmente removidos.
203
203
204
-
## Archiving packages {#archivalguidance}
204
+
## Arquivamento de pacotes {#archivalguidance}
205
205
206
-
Software generally has a finite lifespan, and packages may eventually need to be archived. Archived packages are [archived](https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories)and moved to a dedicated GitHub organization, [ropensci-archive](https://github.com/ropensci-archive). Prior to archiving, the contents of the README file should be moved to an alternative location (such as "README-OLD.md"), and replaced with minimal contents including something like the following:
206
+
O software geralmente tem uma vida útil finita, e os pacotes podem precisar ser arquivados. Os pacotes arquivados são [arquivados](https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories)e movidos para uma organização dedicada do GitHub, [ropensci-archive](https://github.com/ropensci-archive). Antes do arquivamento, o conteúdo do arquivo README deve ser movido para um local alternativo (como "README-OLD.md") e substituído por um conteúdo mínimo, incluindo algo como o seguinte:
207
207
208
208
```md
209
209
# <package name>
@@ -214,18 +214,18 @@ Software generally has a finite lifespan, and packages may eventually need to be
214
214
This package has been archived. The former README is now in [README-old](<link-to-README-old>).
215
215
```
216
216
217
-
The repo status badge should be "unsupported" for formerly released packages, or "abandoned" for former concept or WIP packages, in which case the badge code above should be replaced with:
217
+
O emblema de status do repositório deve ser "unsupported" (sem suporte) para pacotes lançados anteriormente ou "abandoned" (abandonado) para pacotes de conceito anterior ou WIP, caso em que o código do emblema acima deve ser substituído por:
An example of a minimal README in an archived package is in [ropensci-archive/monkeylearn](https://github.com/ropensci-archive/monkeylearn/blob/master/README.md). Once the README has been copied elsewhere and reduced to minimal form, the following steps should be followed:
223
+
Um exemplo de um README mínimo em um pacote arquivado está em [ropensci-archive/monkeylearn](https://github.com/ropensci-archive/monkeylearn/blob/master/README.md). Depois que o LEIAME tiver sido copiado em outro lugar e reduzido à forma mínima, você deverá seguir as etapas a seguir:
224
224
225
-
-[ ]Close issues with a sentence explaining the situation and linking to this guidance.
226
-
-[ ]Archive the repository on GitHub (also under repo settings).
227
-
-[ ]Transfer the repository to[ropensci-archive](https://github.com/ropensci-archive), or request an [rOpenSci staff member](https://ropensci.org/about/#team)to transfer it (you can email`[email protected]`).
225
+
-[ ]Encerre os problemas com uma frase que explique a situação e faça um link para esta orientação.
226
+
-[ ]Arquive o repositório no GitHub (também nas configurações do repositório).
227
+
-[ ]Transfira o repositório para[ropensci-archive](https://github.com/ropensci-archive) ou solicite um [membro da equipe do rOpenSci](https://ropensci.org/about/#team)para transferi-lo (você pode enviar um e-mail para`[email protected]`).
228
228
229
-
Archived packages may be unarchived if authors or a new person opt to resume maintenance. For that please contact rOpenSci. They are transferred to the ropenscilabs organization.
229
+
Os pacotes arquivados podem ser desarquivados se os autores ou uma nova pessoa optarem por retomar a manutenção. Para isso, entre em contato com a rOpenSci. Eles serão transferidos para a organização ropenscilabs.
0 commit comments