Skip to content

Commit 9a37b4c

Browse files
kumekaykumekay
committed
Merge branch 'feat/workflow_diagrams' into 'main'
feat: Create mermaid workflow diagrams Closes PACMAN-1122 See merge request espressif/idf-component-manager!506
2 parents f2e71fd + 3d1e392 commit 9a37b4c

File tree

7 files changed

+178
-0
lines changed

7 files changed

+178
-0
lines changed

‎CONTRIBUTING.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,25 @@
11
# Contributing to IDF Component Manager
2+
23
We welcome all contributions to the Component Manager project!
34

45
You can contribute by fixing bugs, adding features, adding documentation, or reporting an [issue](https://github.com/espressif/idf-component-manager/issues). We accept contributions via [GitHub Pull Requests](https://docs.github.com/en/github/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests).
56

67
Before reporting an issue, make sure you've searched for a similar one that was already created. If you are reporting a new issue, please follow the Issue Template.
78

89
## Writing integration tests
10+
911
For information about tests, refer to the following documents:
12+
1013
- [integration_tests/README.md](integration_tests/README.md)
1114
- [integration_tests/version_solver_components/README.md](integration_tests/version_solver_components/README.md)
1215
- [integration_tests/managed_components_sources/README.md](integration_tests/managed_components_sources/README.md)
1316

1417
## Contributing to the documentation
1518

1619
See [docs/README.md](docs/README.md).
20+
21+
## Workflow diagrams
22+
23+
- [Downloading dependencies](contributing_docs/diagrams/download_dependencies.md)
24+
- [Component download using WebServiceSource](contributing_docs/diagrams/web_service_download.md)
25+
- [Validate hash file equals hash of directory](contributing_docs/diagrams/validate_hashfile_eq_hashdir.md)

‎contributing_docs/diagrams/download_dependencies.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
```mermaid
2+
flowchart TD
3+
classDef exception fill:#ff6054,stroke:#b80c00,stroke-width:2px,color:#000;
4+
5+
download_deps([Download dependencies])
6+
solve_deps[Solve dependencies]
7+
detect_unused[Detect unused dependencies]
8+
9+
download_deps --> solve_deps
10+
solve_deps --> detect_unused
11+
detect_unused --> S1
12+
13+
subgraph S1[Process dependency]
14+
direction LR
15+
16+
subgraph S2[PRE DOWNLOAD CHECK]
17+
direction TB
18+
19+
S2_is_source_downloadable{Is component source downloadable?}
20+
S2_is_component_exist{"Is component exist in managed_components directory?"}
21+
S2_is_overwrite_set{"Is OVERWRITE_MANAGED_COMPONENTS set?"}
22+
S2_check_local[Check local changes]
23+
S2_download_dep[Download dependency]
24+
25+
S2_is_source_downloadable -- No --> S2_download_dep
26+
S2_is_source_downloadable -- Yes --> S2_is_component_exist
27+
S2_is_component_exist -- No --> S2_download_dep
28+
S2_is_component_exist -- Yes --> S2_is_overwrite_set
29+
S2_is_overwrite_set -- No --> S2_check_local
30+
S2_is_overwrite_set -- Yes --> S2_download_dep
31+
end
32+
33+
subgraph S3[CHECK LOCAL CHANGES]
34+
direction TB
35+
36+
S3_is_strict_set{"Is STRICT_CHECKSUM set?"}
37+
S3_validate_hashfile_eq_hashdir[Validate hashfile_eq_hashdir]
38+
S3_check_up_to_date[Check up to date]
39+
S3_is_valid{Is valid?}
40+
S3_component_modified[Component Modified]:::exception
41+
42+
S3_is_strict_set -- No --> S3_check_up_to_date
43+
S3_is_strict_set -- Yes --> S3_validate_hashfile_eq_hashdir
44+
S3_validate_hashfile_eq_hashdir --> S3_is_valid
45+
S3_is_valid -- No --> S3_component_modified
46+
S3_is_valid -- Yes --> S3_check_up_to_date
47+
end
48+
49+
subgraph S4[CHECK UP TO DATE]
50+
direction TB
51+
52+
S4_is_component_has_hash{Is downloadable component has hash?}
53+
S4_is_strict_set{"Is STRICT_CHECKSUM set?"}
54+
S4_download_checksums[Download component checksums]
55+
S4_is_checksums_exist{Is checksums exist?}
56+
S4_validate_checksums[Validate checksums]
57+
S4_validate_hash_eq_hashfile[Validate hash_eq_hashfile]
58+
S4_validate_hash_eq_hashdir[Validate hash_eq_hashdir]
59+
S4_is_valid{Is valid?}
60+
S4_fetching_error[Fetching error]:::exception
61+
S4_download_dep[Download dependency]
62+
S4_add_to_dep_list[Add to downloaded dependencies list]
63+
64+
S4_is_component_has_hash -- No --> S4_fetching_error
65+
S4_is_component_has_hash -- Yes --> S4_is_strict_set
66+
S4_is_strict_set -- No --> S4_validate_hash_eq_hashfile
67+
S4_is_strict_set -- Yes --> S4_download_checksums
68+
S4_download_checksums --> S4_is_checksums_exist
69+
S4_is_checksums_exist -- No --> S4_validate_hash_eq_hashdir
70+
S4_is_checksums_exist -- Yes --> S4_validate_checksums
71+
S4_validate_hash_eq_hashfile --> S4_is_valid
72+
S4_validate_checksums --> S4_is_valid
73+
S4_validate_hash_eq_hashdir --> S4_is_valid
74+
S4_is_valid -- No --> S4_download_dep
75+
S4_is_valid -- Yes --> S4_add_to_dep_list
76+
end
77+
78+
subgraph S5[DOWNLOAD DEPENDENCY]
79+
direction TB
80+
81+
S5_download_dep[Download dependency from source]
82+
S5_is_source_downloadable{Is component source downloadable?}
83+
S5_validate_hashfile_eq_hashdir[Validate hashfile_eq_hashdir]
84+
S5_is_valid{Is valid?}
85+
S5_fetching_error[Fetching error]:::exception
86+
S5_add_to_dep_list[Add to downloaded dependencies list]
87+
88+
S5_download_dep --> S5_is_source_downloadable
89+
S5_is_source_downloadable -- No --> S5_add_to_dep_list
90+
S5_is_source_downloadable -- Yes --> S5_validate_hashfile_eq_hashdir
91+
S5_validate_hashfile_eq_hashdir --> S5_is_valid
92+
S5_is_valid -- No --> S5_fetching_error
93+
S5_is_valid -- Yes --> S5_add_to_dep_list
94+
end
95+
96+
S2 ~~~ S3
97+
S3 ~~~ S4
98+
S4 ~~~ S5
99+
end
100+
```

‎contributing_docs/diagrams/validate_hashfile_eq_hashdir.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
```mermaid
2+
flowchart TD
3+
classDef exception fill:#ff6054,stroke:#b80c00,stroke-width:2px,color:#000;
4+
5+
validate_hashfile_eq_hashdir([Validate hashfile_eq_hashdir])
6+
is_checksums_exist{"Is CHECKSUMS.json exists?"}
7+
validate_checksums[Validate checksums]
8+
is_component_hash_exist{"Is .component_hash exist?"}
9+
validate_hash_eq_hashdir[Validate hash_eq_hashdir]
10+
hash_not_found[Hash Not Found]:::exception
11+
12+
validate_hashfile_eq_hashdir --> is_checksums_exist
13+
is_checksums_exist -- No --> is_component_hash_exist
14+
is_checksums_exist -- Yes --> validate_checksums
15+
is_component_hash_exist -- No --> hash_not_found
16+
is_component_hash_exist -- Yes --> validate_hash_eq_hashdir
17+
```

‎contributing_docs/diagrams/web_service_download.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
```mermaid
2+
flowchart TD
3+
classDef exception fill:#ff6054,stroke:#b80c00,stroke-width:2px,color:#000;
4+
5+
web_service_source_download([WebServiceSource download])
6+
is_component_has_hash{Is downloadable component has hash?}
7+
is_component_has_version{Is downloadable component has version?}
8+
is_component_exist_in_cache{Is component exist in cache?}
9+
validate_hash_eq_hashdir[Validate hash_eq_hashdir]
10+
is_valid{Is valid?}
11+
download_component["
12+
Download component
13+
Copy to cache and managed_components
14+
"]
15+
download_checksums["
16+
Download CHECKSUMS.json
17+
Copy to cache and managed_components
18+
"]
19+
copy_from_cache["
20+
Copy component
21+
from cache to managed_components
22+
"]
23+
return_download_path[Return download path]
24+
fetching_error[Fetching error]:::exception
25+
26+
web_service_source_download --> is_component_has_hash
27+
is_component_has_hash -- No --> fetching_error
28+
is_component_has_hash -- Yes --> is_component_has_version
29+
is_component_has_version -- No --> fetching_error
30+
is_component_has_version -- Yes --> is_component_exist_in_cache
31+
is_component_exist_in_cache -- No --> download_component
32+
is_component_exist_in_cache -- Yes --> validate_hash_eq_hashdir
33+
validate_hash_eq_hashdir --> is_valid
34+
is_valid -- No --> download_component
35+
is_valid -- Yes --> copy_from_cache
36+
copy_from_cache --> return_download_path
37+
download_component --> download_checksums
38+
download_checksums --> return_download_path
39+
```

‎idf_component_manager/dependencies.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -413,6 +413,8 @@ def download_project_dependencies(
413413
"""
414414
Solves dependencies and download components (only talk about resolve-required scenario)
415415
416+
For a detailed workflow, see `contributing_docs/diagrams/download_dependencies.md`.
417+
416418
By default, we run as local-first mode, the process is:
417419
- read existing lock file first, get the solved_components
418420
- use the solved_components with the version solver, to see if solution is still valid

‎idf_component_tools/hash_tools/validate.py‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,8 @@ def validate_hashfile_eq_hashdir(root: t.Union[str, Path]) -> None:
6868
1. Validate hash of each file in the component directory, if CHECKSUMS_FILENAME is present
6969
2. Validate hashsum of the component directory, if HASH_FILENAME is present
7070
71+
For a detailed workflow, see `contributing_docs/diagrams/validate_hashfile_eq_hashdir.md`.
72+
7173
:param root: Path to the component
7274
:raises ComponentNotFoundError: Component path does not exist
7375
:raises HashNotFoundError: Hash file does not exist

‎idf_component_tools/sources/web_service.py‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -275,6 +275,15 @@ def normalized_name(self, name):
275275
return name
276276

277277
def download(self, component: 'SolvedComponent', download_path: str) -> str:
278+
"""Download component from the web service.
279+
280+
For a detailed workflow, see `contributing_docs/diagrams/web_service_download.md`.
281+
282+
:param component: Component to download
283+
:param download_path: Destination path for the downloaded component
284+
:raises FetchingError: If there is an error during the download process.
285+
:return: Path to the downloaded component.
286+
"""
278287
from idf_component_tools.registry.service_details import get_storage_client
279288

280289
# Check for required components

0 commit comments

Comments
 (0)