1 | # Contribution
|
2 |
|
3 | > Go to [GitHub project](https://github.com/Azure/Azurite/projects) page or [GitHub issues](https://github.com/Azure/Azurite/issues) for the milestone and TODO items we are used for tracking upcoming features and bug fixes.
|
4 |
|
5 | ## Azurite V3 Features Implementation
|
6 |
|
7 | Every Azure Storage REST APIs maps to one handler method. Handler methods throwing `NotImplementedError` should be implemented.
|
8 |
|
9 | Every handler will talk to persistence layer directly. We make implements of persistency layer abstract by creating interfaces. `LokiBlobDataStore` is one of the implementation based on Loki database used by Azurite V3.
|
10 |
|
11 | ## Debug
|
12 |
|
13 | In the root of the repository, we have provided pre-defined debugging scripts. This makes it easy to debug in Visual Studio Code with simple F5 click for debug configuration "Azurite Blob Service" or "Azurite Queue Service".
|
14 |
|
15 | Manually follow following steps to build and run all services in Azurite:
|
16 |
|
17 | ```bash
|
18 | npm ci
|
19 | npm run azurite
|
20 | ```
|
21 |
|
22 | Or build and run a certain service like Blob service:
|
23 |
|
24 | ```bash
|
25 | npm ci
|
26 | npm run blob
|
27 | ```
|
28 |
|
29 | ## Debug with SQL based Persisted Metadata Storage
|
30 |
|
31 | By default, Azurite leverages loki as metadata database.
|
32 | However, loki limits Azurite's scalability and extensibility.
|
33 | Set environment variable `AZURITE_DB=dialect://[username][:password][@]host:port/database` to make Azurite blob service switch to a SQL database based metadata storage, like MySql, SqlServer.
|
34 |
|
35 | For example, connect to MySql or SqlServer by set environment variables:
|
36 |
|
37 | ```bash
|
38 | set AZURITE_DB=mysql://root:my-secret-pw@127.0.0.1:3306/azurite_blob
|
39 | set AZURITE_DB=mssql://username:password@localhost:1024/azurite_blob
|
40 | ```
|
41 |
|
42 | > Note. Need to manually create database before starting Azurite instance.
|
43 |
|
44 | > Tips. Create database instance quickly with docker, for example `docker run --name mysql -p 3306:3306 -e MYSQL_ROOT_PASSWORD=my-secret-pw -d mysql:latest`. And grant external access and create database `azurite_blob` using `docker exec mysql mysql -u root -pmy-secret-pw -e "GRANT ALL PRIVILEGES ON *.* TO 'root'@'%' WITH GRANT OPTION; FLUSH PRIVILEGES; create database azurite_blob;"`. Notice that, above commands are examples, you need to carefully define the access permissions in your production environment.
|
45 |
|
46 | ## Develop for Visual Studio Code Extension
|
47 |
|
48 | Select and start Visual Studio Code debug configuration "Run Extension".
|
49 |
|
50 | ## Testing
|
51 |
|
52 | For every newly implemented REST API and handler, there should be at least coverage from 1 unit / integration test case.
|
53 |
|
54 | We also provide a predefined Visual Studio Code debug configuration "Current Mocha", allowing you to execute mocha tests within the currently opended file.
|
55 |
|
56 | Or manually execute all test cases:
|
57 |
|
58 | ```bash
|
59 | npm ci
|
60 | npm run test
|
61 | ```
|
62 |
|
63 | ## PR
|
64 |
|
65 | Make sure test cases are added for the changes you made. And send a PR to `dev` branch for Azurite V3 or later development, `dev-legacy` branch for Azurite V2.
|
66 |
|
67 | ## Regeneration Protocol Layer from Swagger by Autorest
|
68 |
|
69 | 1. Install autorest by `npm install -g autorest`
|
70 | 2. Clone autorest TypeScript server generator to some local path
|
71 | - `git clone --recursive https://github.com/xiaoningliu/autorest.typescript.server`
|
72 | 3. Go to cloned autorest.typescript.server folder and build autorest server
|
73 | - `npm install`
|
74 | - `npm install -g gulp`
|
75 | - `npm run build`
|
76 | 4. Go to package.json of Azurite repo, update `build:autorest:blob` and `build:autorest:queue` to point to the local generator cloned path
|
77 | 5. Generate by go to Azurite root folder and run
|
78 | - `npm run build:autorest:queue`
|
79 | - `npm run build:autorest:blob`
|