Skip to content

RFC: File Organization Convention for v9 Packages #24332

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
TristanWatanabe merged 5 commits into from
Aug 22, 2022
Merged

RFC: File Organization Convention for v9 Packages #24332

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
923b32b
Add RFC
TristanWatanabe Aug 10, 2022
0d6bfde
nit: update RFC name
TristanWatanabe Aug 10, 2022
51f6399
nit: update title
TristanWatanabe Aug 10, 2022
b72c06a
nit: more descriptive
TristanWatanabe Aug 10, 2022
e34e692
more descriptive folder structure for src
TristanWatanabe Aug 10, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions rfcs/shared/build-system/07-standard-package-structure-for-v9.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# RFC: File Organization Convention for v9 Packages

Contributors: @TristanWatanabe, @Hotell

## Summary

Fluent v9 is currently lacking a standard on how v9 package files should be structured. This RFC aims to provide a single source of truth on how files should be organized within each v9 package to provide consistency across all v9 packages and to prevent shipping any unnecessary files to npm.

## Problem Statement

Fluent v9 does not have a defined standard on how v9 files should be organized within each respective package. There is currently no standard for where asset files and documentation files such as specs and migration guides should be stored which leads to inconsistency, clutter and shipment of irrelevant files to npm.

## Detailed Design or Proposal

The proposed folder organization can be seen below:

```
|- docs/
|- assets/
|- MIGRATION.md
|- SPEC.md
|- stories/
|- assets/
|- {componentName}/ //story files
|- e2e/
|- assets/
|- e2e tests
|- src/
|- common/

@Hotell Hotell Aug 23, 2022

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this common is root of evil regarding type-checking etc :P, can we remove it ? #23976

@TristanWatanabe TristanWatanabe Aug 26, 2022

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Being addressed in #24543

|- components/ //implementation and test files
|- index.ts
|- {componentName}.ts
CHANGELOG.json
CHANGELOG.md
package.json
README.md
```

We're already following this convention when it comes to e2e so most of the work will be extracting stories out of the `src` folder and moving those to the root of the package. The asset files will also need to be moved to the appropriate `assets` subfolder. And finally, the `.npmignore` file will then be updated to ignore any asset files and files living within the documentation folder.

## Pros and Cons

### Pros

- Defined standard for v9 package folder structure for developers to reference.
- Prevents shipment of unnecessary files to npm.
- Decoupling to subfolders will allow for better scope alignment for future CI work.

### Cons

- More moving of files around.

## Open Issues

- [#22289](https://github.com/microsoft/fluentui/issues/22289)