Skip to content

Commit c250157

Browse files
marcosqlbimarcosqlbi
committed
Add contribution guidelines for small, medium, and large DAX libraries
1 parent 5fe5b66 commit c250157

4 files changed

Lines changed: 145 additions & 100 deletions

File tree

‎_mydocs/contribute/daxlib-libraries.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
layout: page
3+
title: Contribute to DAX Lib open-source libraries
4+
menu_title: DAX Lib libraries
5+
published: true
6+
date: 2025-10-17
7+
modified: 2025-10-17
8+
order: /05
9+
next_reading: true
10+
---
11+
12+
**TODO**
13+
1) Fork one of the dev-daxlib repos based corresponding to the library name.
14+
2) Apply the change, commit, and submit a Pull Request.
15+
3) Wait for review and approval.

‎_mydocs/contribute/fork-daxlib.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
---
2+
layout: page
3+
title: Contribute Small Libraries to DAX Lib
4+
menu_title: Small libraries
5+
published: true
6+
date: 2025-10-17
7+
modified: 2025-10-17
8+
order: /03
9+
next_reading: true
10+
---
11+
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/daxlib/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.
15+
16+
You can follow these steps to add a new package to DAX Lib:
17+
18+
1. **Fork** the DAX Lib repository [https://github.com/daxlib/daxlib/fork](https://github.com/daxlib/daxlib/fork).
19+
20+
This creates a personal copy of the repository in your GitHub account.
21+
22+
**Remarks**:
23+
24+
Do not make changes directly on the `main` branch. Always create a separate branch for each change you want to make. For example, `add-my-package-version-1.0.0`. This keeps your work isolated until it's reviewed and approved.
25+
26+
2. **Create a folder** for your package in `/packages/` and follow the [naming conventions](naming-conventions.md) for both the folder structure and name.
27+
28+
You can optionally use the [DaxLib.Sample](https://github.com/daxlib/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.
29+
30+
Example: for a library named `Contoso.Conversion` with version `1.0.0`, the folder structure should be:
31+
32+
```bash
33+
/packages/c/contoso.conversion/1.0.0/
34+
```
35+
36+
3. **Create the manifest** in `manifest.daxlib` file.
37+
38+
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/daxlib/daxlib/blob/main/schemas/manifest/1.0.0/manifest.1.0.0.schema.json) for the complete specification of available properties.
39+
40+
Example: for a library named `Contoso.Conversion` with version `1.0.0`, the manifest file should be located at:
41+
42+
```bash
43+
/packages/c/contoso.conversion/1.0.0/manifest.daxlib
44+
```
45+
46+
4. **Create the DAX user-defined functions** in `lib/functions.tmdl` and follow the [naming conventions](naming-conventions.md) for the function names.
47+
48+
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.
49+
50+
**Remarks**:
51+
- The `functions.tmdl` file should contain only the function definitions without the `createOrReplace` command.
52+
- 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).
53+
- Each UDF must include the mandatory annotations: `DAXLIB_PackageId` and `DAXLIB_PackageVersion`.
54+
55+
Example: for a library named `Contoso.Conversion` with version `1.0.0` the annotations should be:
56+
57+
``` text
58+
annotation DAXLIB_PackageId = Contoso.Conversion
59+
annotation DAXLIB_PackageVersion = 1.0.0
60+
```
61+
62+
5. **(Optional) Add a custom icon for your library**
63+
64+
You can include a custom icon for your library by adding a PNG file inside the library's folder.
65+
66+
**Remarks**:
67+
- The icon file must be in PNG format (`.PNG`), with a maximum size of 100 KB.
68+
69+
Example: for a library named `Contoso.Conversion` with version `1.0.0`, place the icon file at:
70+
71+
```bash
72+
/packages/c/contoso.conversion/1.0.0/icon.png
73+
```
74+
75+
If you include a library icon, you must also update the `manifest.daxlib` to specify the file path.
76+
77+
```json
78+
{
79+
// ...other manifest properties...
80+
"icon": "/icon.png"
81+
}
82+
```
83+
84+
6. **(Optional) Add a README file**
85+
86+
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.
87+
88+
**Remarks**:
89+
- The file must be in Markdown format (`.MD`), with a maximum size of 100 KB.
90+
- For security reasons, only a limited set of Markdown features are supported, and external links may be restricted to trusted domains.
91+
92+
Example: for a library named `Contoso.Conversion` with version `1.0.0`, place the README file at:
93+
94+
```bash
95+
/packages/c/contoso.conversion/1.0.0/README.md
96+
```
97+
98+
If you include a README file, you must also update the `manifest.daxlib` to specify the file path.
99+
100+
```json
101+
{
102+
// ...other manifest properties...
103+
"readme": "/README.md"
104+
}
105+
```
106+
107+
7. **Create a pull request** to publish the library on [daxlib.org](https://daxlib.org/)
108+
109+
- Go [here](https://github.com/daxlib/daxlib/pull/new) to create a new pull request from your forked repository to the official DAX Lib repository.
110+
- The pull request must be approved manually by DaxLib owners/maintainers.
111+
- When the pull request is approved, the package is immediately published.

‎_mydocs/contribute/github-repo.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
layout: page
3+
title: Contribute Medium-Large Libraries to DAX Lib
4+
menu_title: Medium-Large libraries
5+
published: true
6+
date: 2025-10-17
7+
modified: 2025-10-17
8+
order: /04
9+
next_reading: true
10+
---
11+
12+
You don’t have to create a repository for your DAX library on daxlib.org, but it’s a smart move if you expect the library to grow. A GitHub repo helps you track issues, accept contributions, and manage changes easily.
13+
14+
To create a GitHub repository for your DAX library, ensure you have a GitHub account; if not, create one. Then, follow the instructions at [https://github.com/daxlib/lib-quickstart-template](https://github.com/daxlib/lib-quickstart-template)
15+

‎_mydocs/contribute/index.md‎

Lines changed: 4 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -9,103 +9,7 @@ order: /02
99
next_reading: true
1010
---
1111

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/daxlib/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.
15-
16-
You can follow these steps to add a new package to DAX Lib:
17-
18-
1. **Fork** the DAX Lib repository [https://github.com/daxlib/daxlib/fork](https://github.com/daxlib/daxlib/fork).
19-
20-
This creates a personal copy of the repository in your GitHub account.
21-
22-
**Remarks**:
23-
24-
Do not make changes directly on the `main` branch. Always create a separate branch for each change you want to make. For example, `add-my-package-version-1.0.0`. This keeps your work isolated until it's reviewed and approved.
25-
26-
2. **Create a folder** for your package in `/packages/` and follow the [naming conventions](naming-conventions.md) for both the folder structure and name.
27-
28-
You can optionally use the [DaxLib.Sample](https://github.com/daxlib/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.
29-
30-
Example: for a library named `Contoso.Conversion` with version `1.0.0`, the folder structure should be:
31-
32-
```bash
33-
/packages/c/contoso.conversion/1.0.0/
34-
```
35-
36-
3. **Create the manifest** in `manifest.daxlib` file.
37-
38-
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/daxlib/daxlib/blob/main/schemas/manifest/1.0.0/manifest.1.0.0.schema.json) for the complete specification of available properties.
39-
40-
Example: for a library named `Contoso.Conversion` with version `1.0.0`, the manifest file should be located at:
41-
42-
```bash
43-
/packages/c/contoso.conversion/1.0.0/manifest.daxlib
44-
```
45-
46-
4. **Create the DAX user-defined functions** in `lib/functions.tmdl` and follow the [naming conventions](naming-conventions.md) for the function names.
47-
48-
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.
49-
50-
**Remarks**:
51-
- The `functions.tmdl` file should contain only the function definitions without the `createOrReplace` command.
52-
- 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).
53-
- Each UDF must include the mandatory annotations: `DAXLIB_PackageId` and `DAXLIB_PackageVersion`.
54-
55-
Example: for a library named `Contoso.Conversion` with version `1.0.0` the annotations should be:
56-
57-
``` text
58-
annotation DAXLIB_PackageId = Contoso.Conversion
59-
annotation DAXLIB_PackageVersion = 1.0.0
60-
```
61-
62-
5. **(Optional) Add a custom icon for your library**
63-
64-
You can include a custom icon for your library by adding a PNG file inside the library's folder.
65-
66-
**Remarks**:
67-
- The icon file must be in PNG format (`.PNG`), with a maximum size of 100 KB.
68-
69-
Example: for a library named `Contoso.Conversion` with version `1.0.0`, place the icon file at:
70-
71-
```bash
72-
/packages/c/contoso.conversion/1.0.0/icon.png
73-
```
74-
75-
If you include a library icon, you must also update the `manifest.daxlib` to specify the file path.
76-
77-
```json
78-
{
79-
// ...other manifest properties...
80-
"icon": "/icon.png"
81-
}
82-
```
83-
84-
6. **(Optional) Add a README file**
85-
86-
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.
87-
88-
**Remarks**:
89-
- The file must be in Markdown format (`.MD`), with a maximum size of 100 KB.
90-
- For security reasons, only a limited set of Markdown features are supported, and external links may be restricted to trusted domains.
91-
92-
Example: for a library named `Contoso.Conversion` with version `1.0.0`, place the README file at:
93-
94-
```bash
95-
/packages/c/contoso.conversion/1.0.0/README.md
96-
```
97-
98-
If you include a README file, you must also update the `manifest.daxlib` to specify the file path.
99-
100-
```json
101-
{
102-
// ...other manifest properties...
103-
"readme": "/README.md"
104-
}
105-
```
106-
107-
7. **Create a pull request** to publish the library on [daxlib.org](https://daxlib.org/)
108-
109-
- Go [here](https://github.com/daxlib/daxlib/pull/new) to create a new pull request from your forked repository to the official DAX Lib repository.
110-
- The pull request must be approved manually by DaxLib owners/maintainers.
111-
- When the pull request is approved, the package is immediately published.
12+
Depending on the size and complexity of your DAX library, you can choose one of the following methods to contribute it to DAX Lib:
13+
1. For small libraries (a few functions), follow the [Contribute Small Libraries to DAX Lib](fork-daxlib.md) guide.
14+
2. For medium to large libraries (more functions, more complex logic), consider creating a dedicated GitHub repository by following the [Contribute Medium-Large Libraries to DAX Lib](github-repo.md) guide.
15+
3. If you want to contribute to one DaxLib prefixed library that is maintained by the DaxLib organization, follow the [Contribute to DAX Lib open-source libraries](daxlib-libraries.md) guide.

0 commit comments

Comments
 (0)