Hacktoberfest 2026: những issue maintainer đã đánh dấu cho tháng Mười, đang mở và phù hợp người mới. Xem issue Hacktoberfest

MAINT: Refactor `dsc-lib` for consistency, library API usage, and maintainability

Đang mở
  • Có gì không ổn?
#1,391 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức phù hợp với người mới
25/100
Loại issue
Tái cấu trúc
Độ rõ ràng
Cần làm rõ
Mức độ hoạt động
Đình trệ
Công nghệ
rust
Lĩnh vực
backend-api-design, developer-experience

Hướng nghiên cứu

Bắt đầu bằng việc xem xét bố cục crate dsc-lib, đặc biệt là các module types và functions, module dscresources và các test hiện có. So sánh vị trí của các test công khai và riêng tư với tests/integration và src/tests, sau đó xác định một tập con tập trung của công việc nhất quán được đề xuất. Done cần được định nghĩa là một phạm vi đã được thống nhất, trong đó các thay đổi tương ứng về API, tài liệu, cách đặt tên và test đã hoàn tất mà không làm hỏng dsc CLI hoặc các bên sử dụng thư viện.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

Dev-UX Needs Triage
Summary of the new feature / enhancement

As a maintainer of the dsc-lib crate and integrating developer of the same crate,
I want to be able to more quickly navigate, contribute, test, document, and reference the types and functions in the library
So that I can contribute and integrate more quickly and reliably.

The layout and library API for dsc-lib has grown organically from the beginning of the project. Along the way, we've learned a lot about writing idiomatic and performant Rust code that differs from the current structure.

Additionally, when we first began work on dsc-lib, we worked under the assumption that the only Rust projects that would take a dependency on the library are the dsc CLI and a limited set of crates developed in this monorepo. Now that the Bicep local extension depends on dsc-lib and we plan to develop a Development Kit in Rust for DSC resources and extensions, we should carefully consider updating the library to follow more consistent conventions for the library APIs and structure.

Proposed technical implementation details (optional)

There are a few different areas we can pursue as part of this overall effort:

  1. Decomposing large rust files into submodules with the re-export pattern.

    We're currently using this pattern to various degrees with the types module. We're almost using this pattern for the functions, except that the submodules are public, so you reference a function type as dsc_lib::functions::<snake_case_name>::<PascalCaseName>. Making this change would enable a simpler access for these types, like dsc_lib::functions::CreateArray instead of dsc_lib::functions::create_array::CreateArray.

    This would also enable decomposing larger files with numerous types into smaller files that are easier to read, maintain, and reason about.

    [!NOTE]
    While out of scope for this issue, it will also make it easier for us to extract subsets of functionality into separate crates to improve compile time performance (for Rust, the crate is a compilation unit). For example, if we decomposed the dscresources module into a dsc-lib-resources crate and re-exported it from within dsc-lib, any compilation for local development that doesn't affect the decomposed crate is able to reuse prior compilation. I'm not sure the performance benefits are worth this more drastic move, but we might find that to be the case in the future.

  2. Reviewing the naming for structs, functions, and other items for consistency and clarity.

    Currently, we have a mix of naming conventions that have organically grown with the project. We should be more consistent in the naming for types, traits, and functions both to ease general cognitive load for maintainers and to provide a consistent model for integrating developers to rely on.

  3. Standardize reference documentation for items in the library.

    Currently, the reference documentation (triple slash docs above a definition) for the library is in a mixed state. Some definitions have extensive documentation, some have a single line, some are lacking documentation entirely. We should ensure we have coverage of every public item and that the structure we use is consistent. This is critical for integrating developers but also helpful for contributors and maintainers, since reference documentation is surfaced by the Rust Analyzer extension when working on the project.

    We should also consider documenting private items to the same standard, though this only affects maintainers.

  4. Moving shared type definitions into the types module.

    As we move forward with the schema canonicalization effort and adopting the "parse, don't validate" design pattern to improve reliability and coherence for the library, we should consider moving shared type definitions to that module. Not every type should be defined there - manifests belong in their relevant module, for example.

    But some types are defined in a given module and reused across multiple modules as generic types, like ExecutionType.

  5. Moving all Rust tests for public items into the tests/integration suite.

    The primary motivating factor here is build and test timings. When integration tests are colocated with module code, any changes to either the tests or the implementation requires recompilation because the file changed.

    Moving the tests and following the current pattern that mirrors the src directory structure can also help us quickly identify where we are lacking integration tests for the library. Currently, given the existing layout, we need to carefully check every implementation file for test coverage.

  6. Moving all Rust tests for private items into the src/tests folder.

    We don't seem to have many tests that validate the behavior of private items. The vast majority of the tests I reviewed are only validating public items. However, moving the tests to a dedicated unit tests folder will also improve compile times for local development similarly to moving integration tests.

    In the process of moving tests out of the implementation files and into dedicated test files, we should consider whether the unit tests are providing any value over the integration tests.

  7. Enhancing integration tests for faster feedback and improved reliability.

    Currently, we use Pester tests in the dsc folder as acceptance tests for the DSC CLI. We should continue to do so, as the CLI is its own fully separate boundary for users. However, given the need to make the dsc-lib crate available itself, we should provide integration tests that ensure correctness and reliability for the underlying APIs themselves.

    Rust integration tests are also much faster than repeatedly invoking dsc through Pester, so this can improve the local development feedback loop for contributors and maintainers. We can continue to rely on the acceptance tests in the dsc folder for CI.

Ngôn ngữ chính
Rust
Star
536
Fork
76
Merge trung bình
1 ngày 11 giờ
Pull request đã merge (30 ngày)
15

Chuẩn bị môi trường

Mở trong Codespaces

Khởi chạy dev container của dự án ngay trên trình duyệt, bằng tài khoản GitHub của bạn.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của PowerShell/DSC

Tất cả issue của PowerShell/DSC

Issue tương tự

Thêm issue về Rust

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.