Skip to content
This repository was archived by the owner on Feb 6, 2025. It is now read-only.

Commit 08aad9c

Browse files
abruno-abruno-
committed
Readme update
1 parent 0103a0a commit 08aad9c

File tree

2 files changed

+106
-73
lines changed

2 files changed

+106
-73
lines changed

‎README.md

+104-71
Original file line numberDiff line numberDiff line change
@@ -1,60 +1,65 @@
1-
# Allowlist dependencies
1+
# Allowlist Dependencies
22

3-
**NOTE**: _This repo isnt versioned. `master` branch is consumed by default, so every time `master` branch changes, all
4-
repositories will immediatly start consuming the new changes_
3+
> **Note:** This repository is not versioned. The `master` branch is consumed by default, so whenever the `master`
4+
> branch changes, all repositories will immediately start consuming the new changes.
55
6-
**If you need to add or update a library**
7-
,visit [Wiki.](https://sites.google.com/mercadolibre.com/mobile/arquitectura/allowlist)
6+
If you need to add or update a library, please visit
7+
the [Architecture Wiki](https://sites.google.com/mercadolibre.com/mobile/arquitectura/allowlist).
88

9-
### Android
9+
## Android Dependencies
1010

11-
Android allowlist dependencies consist of a set of dependencies that are available for front-ends and high-level
12-
repositories to consume from the Mercadolibre-mobile group.
11+
Android allowlist dependencies consist of a set of libraries that are available for front-ends and low-level
12+
repositories to consume from the **MercadoLibre-mobile** group. Your Frontend should not be declared here nor consumed
13+
by any other FEnd.
1314

14-
This set of dependencies is parsed in the form of a JSON text. The root level property should be called `whitelist`.
15+
These dependencies are defined in JSON format, and the root-level property is called `whitelist`.
1516

16-
Each of the dependencies is a JSON Object that will be matched against each of the unresolved dependencies of the
17-
repository. The repository dependencies will be a string formed as `group:name:version`. The allowlist fields SUPPORTS
18-
regex expressions, so you can form match cases for groups in single strings.
17+
Each dependency is a JSON object that will be matched against the unresolved dependencies of the repository. Repository
18+
dependencies will be strings in the format `group:name:version`. The allowlist fields SUPPORT regex expressions, so you
19+
can define matching cases for groups in single strings.
1920

20-
* Remember that this are regexes, so if you want to declare `com.example` it should be `com\\.example`
21-
* The repository will validate against unresolved dependencies. Thus, if declaring as version `4\\.\\+` it **
22-
will** match against a dependency `4.+` (it wont be for example the string `4.2.3`)
23-
* You can have expirable dependencies by adding the `expires` field. If no field is added, the dependency is
24-
considered as non-expirable
25-
* Warning: expires should not be on wednesday or thursday, as they are to close to the release trains and generate unforseable issues
26-
* If no group / name / version is provided, they will default to `.*` (any string)
21+
### Important Considerations:
2722

28-
JSON Schema:
23+
- Remember these are **regexes**, so if you want to declare `com.example`, you should write it as `com\\.example`.
24+
- Validation is done against unresolved dependencies. If you declare a version as `4\\.\\+`, it **will** match
25+
with `4.+` (but not strings like `4.2.3`).
26+
- The `expires` field its **optional**. If no field is added, the dependency is considered non-expirable.
27+
- **Warning:** Expiring dependencies on Wednesdays or Thursdays will fail CI, as they are too close to release trains and
28+
may cause unforeseen issues.
29+
- If no `group`, `name`, or `version` is provided, they will default to `.*` (any string).
30+
- **All dependencies and fields are sorted**
2931

30-
```
32+
### Basic JSON Schema:
33+
34+
```json
3135
{
3236
"whitelist": [
3337
{
3438
"description": "(optional) description",
3539
"expires": "yyyy-MM-dd",
36-
"group": "group_regex",
37-
"name": "name_regex",
38-
"version": "version_regex"
39-
},
40-
...
40+
"group": "regex_group",
41+
"name": "regex_name",
42+
"version": "regex_version"
43+
}
4144
]
4245
}
4346
```
4447

45-
**How to test locally**:
46-
If you want to try if its working correctly from your fork, just add this line to the \<MODULE-NAME\>/build.gradle:
48+
### How to test Locally (Android):
49+
50+
If you want to verify that your changes work correctly from your fork, simply add this line to your `/<MODULE-NAME>/build.gradle`:
4751

4852
```
4953
ext["allowlistURL"] = "https://raw.githubusercontent.com/YOUR_GITHUB_USER/mobile-dependencies_whitelist/YOUR_GIT_BRANCH/android-whitelist.json"
5054
```
5155

52-
### iOS
56+
## iOS Dependencies
5357

54-
iOS allowlist dependencies consist of a set of dependencies that are available for front-ends and high-level
55-
repositories to consume from the Mercadolibre-mobile group.
58+
iOS allowlist dependencies consist of a set of libraries that are available for front-ends and low-level
59+
repositories to consume from the **MercadoLibre-mobile** group. Your Frontend should not be declared here nor consumed
60+
by any other FEnd.
5661

57-
This set of dependencies is parsed in the form of a JSON text. The root level property should be called `whitelist`.
62+
These dependencies are defined in JSON format, and the root-level property is called `whitelist`.
5863

5964
Each of the dependencies is an object with the following properties:
6065

@@ -66,43 +71,45 @@ Each of the dependencies is an object with the following properties:
6671

6772
#### Optional
6873

74+
- `description`: (optional) some relevant description
6975
- `expires`: You can have expirable dependencies by adding the `expires` field. If no field is added, the dependency is
7076
considered as non-expirable
71-
- `description`: (optional) some relevant description
7277

7378
Example:
7479

75-
```
80+
```json
7681
{
77-
"whitelist": [
78-
# This will match with 'MeliSDK' and version '~>5.+' (version must have ~>5.x)
82+
"whitelist": [
7983
{
80-
"name": "MeliSDK",
81-
"version": "^~>5.[0-9]+$"
82-
},
83-
# This will match with 'MLRecommendations' for any version
84+
"description": "# This will match with 'MeliSDK' and version '~>5.+' (version must have ~>5.x)",
85+
"name": "MeliSDK",
86+
"version": "^~>5.[0-9]+$"
87+
},
8488
{
85-
"name": "MLRecommendations",
86-
"version": null
87-
}]
89+
"description": "# This will match with 'MLRecommendations' for any version",
90+
"name": "MLRecommendations",
91+
"version": null
92+
}]
8893
}
8994
```
9095

9196
## Support for Granular Dependencies:
9297

93-
This functionality provides a more precise management of the scope of dependencies, giving us the ability to select specific consumers for each of them.
98+
This functionality provides a more precise management of the scope of dependencies, giving us the ability to select
99+
specific consumers for each of them.
94100

95-
To activate the granularity feature, it is necessary to introduce a new block within the dependency definition, specifying which Mercado Libre projects will have access to it. This should be done as follows:
101+
To activate the granularity feature, it is necessary to introduce a new block within the dependency definition,
102+
specifying which Mercado Libre projects will have access to it. This should be done as follows:
96103

104+
### Android Platform
97105
#### There are two types of granularity:
98106

99-
* GroupId : You specify the group id of the project that will have access to the dependency.
100-
* Example: `com.mercadolibre.android.example`
107+
* GroupId : You specify the group id of the project that will have access to the dependency.
108+
* Example: `com.mercadolibre.android.example`
101109
* GroupId:name : You specify the group id and the name of the project that will have access to the dependency.
102-
* Example: `com.mercadolibre.android.exambple:exampleModule`
110+
* Example: `com.mercadolibre.android.example:exampleModule`
103111

104-
### Android Platform
105-
```
112+
```json
106113
{
107114
"whitelist": [
108115
{
@@ -123,40 +130,43 @@ To activate the granularity feature, it is necessary to introduce a new block wi
123130
```
124131

125132
### iOS Platform
126-
```
133+
134+
```json
127135
{
128136
"whitelist": [
129137
{
138+
"allows_granular_projects": [
139+
"name_meli_lib",
140+
"MLRecommendations" # Example of a Mercado Libre Dependency Lib Name.
141+
],
130142
"name": "MeliSDK",
131143
"version": "^~>5.[0-9]+$"
132-
"allows_granular_projects": [
133-
"name_meli_lib",
134-
"MLRecommendations" # Example of a Mercado Libre Dependency Lib Name .
135-
]
136144
},
137145
...
138146
]
139147
}
140148
```
141149

142-
143150
## Support for Transitive Dependencies (ONLY ANDROID):
144151

145-
This functionality provides a more precise control over how it is possible to exclude transitive dependencies from our projects.
152+
This functionality provides more precise control over how transitive dependencies can be excluded from projects,
153+
allowing specific consumers to be selected for each one.
146154

147-
This functionality provides a more precise management of the scope of dependencies, giving us the ability to select specific consumers for each of them.
155+
### Blocking Transitive Dependencies:
148156

149-
To activate the transitivity feature, it is necessary to introduce a new block within the dependency definition, specifying two new keys:
150-
1. By default, all dependencies are enabled as transitive. To specify otherwise, it should be configured as false as follows:
151-
` "transitivity" = false `
152-
2. All dependencies that are not transitive should indicate the namespace of the dependency. This can be done as follows:
153-
` "namespace": "com.name.path.path" `
157+
To activate this feature, introduce a new block within the dependency definition with two keys:
154158

155-
Both keys will be found within the ` "transitive_configuration" ` enclosure. Here's an example to visualize it more clearly:
159+
1. **namespace**: For non-transitive dependencies, you must specify the namespace:
160+
`"namespace": "com.name.path.path"`
161+
2. **transitivity**: By default, all dependencies are transitive. To specify otherwise, set it to `false`:
162+
`"transitivity": "false"`
156163

164+
Both keys will be found within the `"transitive_configuration"` node. Here's an example to visualize it more
165+
clearly:
157166

158167
### Android Platform
159-
```
168+
169+
```json
160170
{
161171
"whitelist": [
162172
{
@@ -165,19 +175,42 @@ Both keys will be found within the ` "transitive_configuration" ` enclosure. Her
165175
"version": "2\\.6\\.4",
166176
"transitive_configuration":
167177
{
168-
"transitivity": false,
169-
"namespace": "retrofit2"
178+
"namespace": "retrofit2",
179+
"transitivity": false
170180
}
171181
},
172182
...
173183
]
174184
}
175185
```
176186

177-
It's important to mention that if non-transitive dependency imports are found within classes, they will generate a blocker through the Gradle plugin, preventing the lintAndroid() task executed in CI or locally from completing successfully.
187+
If declared `non-transitive dependency` imports are found in your code, our plugin will **block** the build, preventing
188+
the `lintAndroid()` task from completing successfully in CI or locally.
189+
190+
191+
## Basic Continuous Integration (CI) Checks!!
192+
We have some basic checks placed in our CI to ensure that the allowlist is being used correctly.
193+
The checks can be found [here](https://github.com/mercadolibre/mobile-dependencies_whitelist/blob/master/scripts/checks.sh)
194+
but basically, we are validating the following:
195+
196+
1. **JSON Linter**:
197+
- Uses the cmd `jsonlint <allowlist_file>` to check if the JSON file is well-formed.
198+
- you can install it from [here](https://www.npmjs.com/package/jsonlint)
199+
2. **JSON Sorter Lint**:
200+
- Uses the cmd `jsonsort <allowlist_file> --arrays` to ensure the content of the JSON file is properly sorted, including arrays.
201+
- you can install it from [here](https://www.npmjs.com/package/json-sort-cli)
202+
3. **Expiration Date Validator**:
203+
- Verify that the expiration dates in the JSON file are in the correct format (YYYY-MM-DD).
204+
- Verify that the expiration date isn't a `Wednesdays` or `Thursdays`.
205+
4. **Key Names Validator**:
206+
- Verify that your are using the proper key names in the JSON file.
207+
5. **Version Pattern Validator**:
208+
- Verify that we aren't using dynamic versions for external libs.
209+
210+
Some other checks could be performed, check the CI Error for more information.
178211

212+
## Contexts Allowlist (Deprecated)
179213

180-
# Contexts Allowlist [DEPRECATED]
214+
For more information, check
215+
the [new context allowlist](https://furydocs.io/mobile-apps/v1.5.2/guide/#/lang-en/metrics/02_crash-rate?id=contexts).
181216

182-
For more information consult
183-
the [new context allowlist](https://furydocs.io/mobile-apps/v1.5.2/guide/#/lang-en/metrics/02_crash-rate?id=contexts)

‎scripts/checks.sh

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
#!/bin/bash
22

3-
# check if enviroment $FILE is set
3+
# check if environment $FILE is set
44
if [ -z "$FILE" ]; then
5-
echo 'FILE enviroment variable is not set. for example you could use: export FILE=android-whitelist.json'
5+
echo 'FILE environment variable is not set. for example you could use: export FILE=android-whitelist.json'
66
exit 1;
77
fi
88

0 commit comments

Comments
 (0)