Skip to content

Commit fb5ec52

Browse files
albertospeltaalbertospelta
committed
Update contribution guidelines and naming conventions
1 parent 7181129 commit fb5ec52

2 files changed

Lines changed: 146 additions & 27 deletions

File tree

‎_mydocs/contribute/index.md‎

Lines changed: 81 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -4,39 +4,103 @@ title: Contribute to DAX Lib
44
menu_title: Contribute
55
published: true
66
date: 2025-08-14
7-
modified: 2025-08-25
7+
modified: 2025-09-30
88
order: /02
99
next_reading: true
1010
---
1111

12-
A DAX library is deployed as a package in DAX Lib. A package is a ZIP file that includes a few files (**TODO add package description**).
12+
A DAX library is a collection of DAX user-defined functions (UDFs) authored in TMDL format, along with metadata (such as library name, version, author, etc.) and optional files like a README or an icon.
13+
Development takes place in the [DaxLib GitHub repository](https://github.com/sql-bi/daxlib/), where users can propose new libraries by submitting a pull request (PR).
14+
Once the pull request is approved, the library is automatically packaged as a ZIP file and published on [daxlib.org](https://daxlib.org/), making it available for browsing, installation, and use.
1315

1416
You can follow these steps to add a new package to DAX Lib:
1517

16-
1. **Clone** the GitHub repository [https://github.com/sql-bi/daxlib/](https://github.com/sql-bi/daxlib/).
18+
1. **Fork** the GitHub repository [https://github.com/sql-bi/daxlib/](https://github.com/sql-bi/daxlib/fork).
1719

18-
2. **Create a folder** for your package in `/packages/`, for example by copying the `DaxLib.Sample` package, and follow the [naming conventions](naming-conventions.md) for package, library, and function names.
20+
If you are using Visual Studio Code, you can open the workspace file `packages.code-workspace` to quickly access and work on the packages.
1921

20-
3. **Create the DAX functions** in `functions.tmdl`
22+
2. **Create a folder** for your package in `/packages/` and follow the [naming conventions](naming-conventions.md) for both the folder structure and name.
2123

22-
a. The file `lib/functions.tmdl` contains the source code of the DAX functions in a TMDL `createOrReplace` command. For example, in `test.functions` the name is `/packages/t/test.functions/lib/functions.tmdl`
24+
You can optionally use the [DaxLib.Sample](https://github.com/sql-bi/daxlib/tree/main/packages/d/daxlib.sample/0.1.6) package as a starting point: copy it, rename it according to your library’s name, and then update its contents to match your library.
2325

24-
b. The `functions.tmdl` file contains the function definition using the TMDL syntax following the `createOrReplace` statement
26+
Example: for a library named `Contoso.Conversion` with version `1.0.0`, the folder structure should be:
2527

26-
c. Include mandatory annotations for each function of the library:
28+
```bash
29+
/packages/c/contoso.conversion/1.0.0/
30+
```
31+
32+
3. **Create the manifest** in `manifest.daxlib` file.
33+
34+
The `manifest.daxlib` is a mandatory file contains the package properties in JSON format. You can see the [DaxLib.Sample](https://daxlib.org/package/DaxLib.Sample/#code) package for an example and refer to the [JSON schema](https://github.com/sql-bi/daxlib/blob/main/schemas/manifest/1.0.0/manifest.1.0.0.schema.json) for the complete specification of available properties.
35+
36+
Example: for a library named `Contoso.Conversion` with version `1.0.0`, the manifest file should be located at:
37+
38+
```bash
39+
/packages/c/contoso.conversion/1.0.0/manifest.daxlib
40+
```
41+
42+
4. **Create the DAX user-defined functions** in `lib/functions.tmdl` and follow the [naming conventions](naming-conventions.md) for the function names.
2743

28-
```
29-
annotation DAXLIB_PackageId = <name of library>
30-
annotation DAXLIB_PackageVersion = <version of library>
31-
```
32-
33-
4. **Create the manifest** in the `manifest.daxlib` file
44+
The file `lib/functions.tmdl` is a mandatory file and contains the source code of the DAX user-defined functions using the TMDL syntax. For an example, see the [DaxLib.Sample](https://daxlib.org/package/DaxLib.Sample/#code) package.
45+
46+
Remarks:
47+
- The `functions.tmdl` file should contain only the function definitions without the `createOrReplace` command.
48+
- Optional: add comments describing the function and its parameters to improve readability and usability, as suggested in the [DAX naming convention](https://docs.sqlbi.com/dax-style/dax-naming-conventions#comments).
49+
- Each UDF must include the mandatory annotations: `DAXLIB_PackageId` and `DAXLIB_PackageVersion`.
50+
51+
Example: for a library named `Contoso.Conversion` with version `1.0.0` the annotations should be:
52+
53+
``` text
54+
annotation DAXLIB_PackageId = Contoso.Conversion
55+
annotation DAXLIB_PackageVersion = 1.0.0
56+
```
57+
58+
5. **(Optional) Add a custom icon for your library**
59+
60+
You can include a custom icon for your library by adding a PNG file inside the library's folder.
3461
35-
a. For example, in `test.functions` the name is `/packages/t/test.functions/manifest.daxlib`
62+
Remarks:
63+
- The icon file must be in PNG format (`.PNG`), with a maximum size of 100 KB.
64+
65+
Example: for a library named `Contoso.Conversion` with version `1.0.0`, place the icon file at:
66+
67+
```bash
68+
/packages/c/contoso.conversion/1.0.0/icon.png
69+
```
70+
71+
If you include a library icon, you must also update the `manifest.daxlib` to specify the file path.
72+
73+
```json
74+
{
75+
// ...other manifest properties...
76+
"icon": "/icon.png"
77+
}
78+
```
79+
80+
6. **(Optional) Add a README file**
81+
82+
You can include a README file to provide documentation for your library. It can include general information about the library, usage instructions, examples, and any notes for users.
83+
84+
Remarks:
85+
- The file must be in Markdown format (`.MD`), with a maximum size of 100 KB.
86+
- For security reasons, only a limited set of Markdown features are supported, and external links may be restricted to trusted domains.
87+
88+
Example: for a library named `Contoso.Conversion` with version `1.0.0`, place the README file at:
89+
90+
```bash
91+
/packages/c/contoso.conversion/1.0.0/README.md
92+
```
93+
94+
If you include a README file, you must also update the `manifest.daxlib` to specify the file path.
3695
37-
b. The `manifest.daxlib` file contains the package properties in JSON format. See the [DaxLib.Sample](https://daxlib.org/package/DaxLib.Sample/#code) package for an example and refer to the [JSON schema](https://github.com/sql-bi/daxlib/blob/main/schemas/manifest/1.0.0/manifest.1.0.0.schema.json) for the complete specification of available properties.
96+
```json
97+
{
98+
// ...other manifest properties...
99+
"readme": "/README.md"
100+
}
101+
```
38102
39-
5. **Create a pull request** to publish the library on daxlib.org
103+
7. **Create a pull request** to publish the library on [daxlib.org](https://daxlib.org/)
40104
41105
a. The pull request must be approved manually by DaxLib owners/maintainers.
42106

‎_mydocs/contribute/naming-conventions.md‎

Lines changed: 65 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,19 +3,74 @@ layout: page
33
title: Naming conventions
44
published: true
55
date: 2025-09-20
6-
modified: 2025-09-20
6+
modified: 2025-09-30
77
order: /002
88
next_reading: true
99
---
1010

11-
When creating a new package for DAX Lib, it is important to follow specific naming conventions to ensure consistency and clarity across the platform. Below are the key guidelines to adhere to when naming your package and its components:
12-
1. **Package Folder Name**: The folder name for your package should be in lowercase letters and use dots to separate different levels of hierarchy. For example, if your package is named `Test.Functions`, the folder should be named `test.functions`.
13-
2. **Package and Library Name**: The name of the package and library should follow PascalCase naming conventions, where each word starts with an uppercase letter and there are no spaces or underscores. For example, `Test.Functions` is a valid package name. Exceptions are allowed for well-known acronyms (e.g., `XML`, `JSON`, `SVG`) which can be in uppercase.
14-
3. **Hierarchical Nomenclature**: The package and library name must have a hierarchical
15-
nomenclature, where the first name is the published/author identifier and the second (and following) names identify the library scope. For example, `Contoso.Conversion` is a library of conversion functions made by Contoso, whereas `Northwind.Math.Geometry` is a set of geometrical mathematical functions made by Northwind.
16-
4. **Function Naming**: All functions within the package should be prefixed with the package name to avoid naming conflicts. For example, if your package is named `Test.Functions`, a function named `Sum` should be named `Test.Functions.Sum`. Function names should also follow PascalCase conventions and the [DAX naming conventions for user-defined functions](https://docs.sqlbi.com/dax-style/dax-naming-conventions#user-defined-functions).
17-
5. **Reserved Keywords**: Do not use `Dax.` in the name of the library (Dax as a single word is a reserved keyword in a function name). `DaxLib.` as a prefix is a reserved word for public open-source libraries of common use that are reviewed and approved by DaxLib maintainers. Do not create pull request for new `DaxLib.` libraries.
18-
6. **Folder Structure**: The first level in the folder structure should be a single letter corresponding to the first letter of the package name (for example, a package `test.functions` will be in `/packages/t/test.functions/` folder). This is a technique used to reduce the number of elements in a single folder.
19-
7. **Lowercase for Folders and Files**: All names of folders and files must be in lowercase; the name of the package (with uppercase letters if necessary) is defined in the metadata (`manifest.daxlib` file) of the package.
11+
When creating a new package for DAX Lib, it is important to follow specific conventions to ensure consistency and clarity across the platform. Below are the key guidelines to adhere to when naming your package and its components:
12+
13+
1. **Hierarchical Nomenclature**
14+
15+
- The package name must follow a hierarchical structure, where the first segment is recommended to identify the publisher or author, and the subsequent segments define the library’s scope.
16+
- Do not use built-in DAX function names or other DAX reserved keywords as any segment. See **Reserved Keywords** below for reference.
17+
18+
Examples:
19+
- `Contoso.Conversion` - a library of conversion functions published by Contoso.
20+
- `Northwind.Math.Geometry` - a library of geometrical math functions published by Northwind.
21+
22+
2. **Package Folder Name**
23+
24+
- The folder name for your package should be in lowercase letters and use dots to separate different levels of hierarchy.
25+
26+
Example: for a package named `Contoso.Conversion`, the folder name should be:
27+
28+
```bash
29+
/packages/c/contoso.conversion/
30+
```
31+
32+
3. **Package Name**
33+
34+
- The name of the package should follow PascalCase naming conventions and use dots to separate different levels of hierarchy, where each word starts with an uppercase letter and there are no spaces or underscores.
35+
- Exceptions are allowed for well-known acronyms (e.g., `XML`, `JSON`, `SVG`) which can be in uppercase.
36+
37+
Example: for a package named `Contoso.Conversion`, the name in `manifest.daxlib` should be:
38+
39+
```json
40+
{
41+
"id": "Contoso.Conversion"
42+
// ...other manifest properties...
43+
}
44+
```
45+
46+
4. **Function Naming**
47+
48+
- All functions within the package should be prefixed with the package name to avoid naming conflicts.
49+
- Function names should follow the [DAX naming conventions for user-defined functions](https://docs.sqlbi.com/dax-style/dax-naming-conventions#function-names).
50+
51+
Example: for a package named `Contoso.Conversion`, a function named `CelsiusToKelvin` should defined as:
52+
53+
```yaml
54+
function 'Contoso.Conversion.CelsiusToKelvin' =
55+
# ... function implementation
56+
```
57+
58+
5. **Reserved Keywords**:
59+
60+
- Do not use built-in DAX function names or other DAX reserved keywords in the package name (e.g. `MEASURE`, `FUNCTION`, `DEFINE`, `FILTER`)
61+
- Do not use `Dax.` in the package name (`Dax` as a single word is a reserved keyword in function names).
62+
- Do not use `DaxLib.` as a prefix for package name. This prefix is reserved for public open-source libraries of common use. Do not submit pull requests for new libraries using the `DaxLib.` prefix.
63+
64+
6. **Folder Structure**
65+
66+
- The **first level** structure should be a single letter (lowercase) corresponding to the first letter of the package name. This helps reduce the number of items in a single folder and keeps the repository organized.
67+
- The **second level** should be the package name (lowercase).
68+
- The **third level** should be the package version.
69+
70+
Example: for a package named `Contoso.Conversion` with version `1.0.0`, the folder should be:
71+
72+
```bash
73+
/packages/c/contoso.conversion/1.0.0/
74+
```
2075

2176
By following these naming conventions, you help maintain a well-organized and easily navigable repository of DAX libraries, making it easier for users to find and utilize the functions they need.

0 commit comments

Comments
 (0)