|
1 | | -# Unity UPM Package Template. |
| 1 | +# Internal Plugins dev kit |
2 | 2 |
|
3 | | -The purpose of this template is to give you a head start when creating a new package for Unity. You'll find the repository structure description below as well as why it was built this way. |
4 | | -I assume you already have some basic understanding of what the UPM package is and why you would like to build one. If not, please check out [Creating custom packages](https://docs.unity3d.com/Manual/CustomPackages.html) |
5 | | - |
6 | | -## How to use |
7 | | -* Create a new repository and use this sample repository as a template. |
8 | | -* Run init script `sh <new-package-name> <new-package-namespace>` |
9 | | - * Example1: `sh init com.my-company.unity.awesome-package MyCompany.AwesomePlugin` |
10 | | - * Example2: `sh init com.stansassets.foundation Stansassets.Foundation` |
11 | | -* Open `package.json` and update package metadata. You can do this by selecting `package.json` in the Unity Editor or just use any text editor you like. I would recommend using text editor since there are some additional data that isn't consumed by the Unity in the `package.json` |
12 | | - |
13 | | -## Package manifest |
14 | | -Unity uses the package manifest file `package.json` to manage information about a specific version of a specific package. The package manifest is always at the root of the package and contains crucial information about the package, such as its registered name and version number. [Full Package manifest Unity Guide](https://docs.unity3d.com/Manual/upm-manifestPkg.html) |
15 | | - |
16 | | -### Required attributes |
17 | | -* **name** - The officially registered package name. |
18 | | -* **version** - The package version number (MAJOR.MINOR.PATCH). |
19 | | -* **displayName** - A user-friendly name to appear in the Unity Editor. |
20 | | -* **description** - A brief description of the package. |
21 | | -* **unity** - Indicates the lowest Unity version the package is compatible with. |
22 | | - |
23 | | -### Optional attributes |
24 | | -* **unityRelease** - Part of a Unity version indicating the specific release of Unity that the package is compatible with. |
25 | | -* **dependencies** - A map of package dependencies. |
26 | | -* **keywords** - An array of keywords used by the Package Manager search APIs. |
27 | | -* **author** - Author of the package. |
28 | | - |
29 | | -### npmjs attributes |
30 | | -This is only relevant if you are planning to distribute your package with npmjs. Otherwise, remove listed keywords from the `package.json` template. |
31 | | -I will list attributes that will affect how your package is displayed on the npmjs package page. As an example, you can check out the [Foundation package page](https://www.npmjs.com/package/com.stansassets.foundation). But I would also recommend reading [Full npm-package.json guide](https://docs.npmjs.com/files/package.json.html) |
32 | | - |
33 | | -* **homepage** - The URL to the project homepage. |
34 | | -* **bugs** - The URL to your project issue tracker and/or the email address to which issues should be reported. |
35 | | -* **license** - Specify a license for your package so that people know how they are permitted to use it, and any restrictions you’re placing on it. |
36 | | -* **repository** - Specify the place where your code lives. |
37 | | - |
38 | | -### Package manifest example |
39 | | -This is how `package.json` looks like in our template repository: |
40 | | -```json |
41 | | -{ |
42 | | - "name": "com.stansassets.plugins-dev-kit", |
43 | | - "displayName": "Stans Assets - Package Sample", |
44 | | - "version": "0.0.1-preview", |
45 | | - "unity": "2019.3", |
46 | | - "description": "Package Sample.", |
47 | | - "dependencies": { |
48 | | - "com.stansassets.foundation": "1.0.2" |
49 | | - }, |
50 | | - "keywords": [ |
51 | | - "keyword1", |
52 | | - "keyword2", |
53 | | - "keyword3" |
54 | | - ], |
55 | | - "license": "MIT", |
56 | | - "author": { |
57 | | - "name": "Stan's Assets", |
58 | | - |
59 | | - "url": "https://stansassets.com/" |
60 | | - }, |
61 | | - |
62 | | - "homepage": "https://api.stansassets.com/", |
63 | | - "bugs": { |
64 | | - "url": "https://github.com/StansAssets/com.stansassets.foundation/issues", |
65 | | - |
66 | | - }, |
67 | | - "repository": { |
68 | | - "type": "git", |
69 | | - "url": "ssh://[email protected]:StansAssets/com.stansassets.foundation.git" |
70 | | - }, |
71 | | -} |
72 | | -``` |
73 | | - |
74 | | -## Repository structure |
75 | | -* `init` - CLI init script. |
76 | | -* `.github` - GitHub Settings & Actions |
77 | | -* `.gitignore` - Git ignore file designed to this specific repository structure. |
78 | | -* `README.md` - text file that introduces and explains a project. |
79 | | -* `PackageSampleProject` - Team shared project for package development. |
80 | | -* `com.stansassets.plugins-dev-kit` - UMP package. |
81 | | - |
82 | | -This structure was chosen for the following reasons: |
83 | | -1. Scalability. Since the package isn't located in the repository root, you can host more than one package in the repository. |
84 | | -2. You have the Unity Project that your team may use to work on a package. There are a few benefits of having the project already set: |
85 | | - * Team members (especially the ones who haven't worked with the project before) won't have to go thought the project set up. |
86 | | - * Project already linked to the package using a [local](https://docs.unity3d.com/Manual/upm-localpath.html) relative path. |
87 | | - * You can have Additional scripts, resources, another package. Whatever could help you develop the package but should not be part of the package release. |
88 | | - * You can have additional settings defined in your project `manifest.json` For example project from this template has stansassets npmjs score registry defined. |
89 | | - |
90 | | -```json |
91 | | -"scopedRegistries": [ |
92 | | - { |
93 | | - "name": "npmjs", |
94 | | - "url": "https://registry.npmjs.org/", |
95 | | - "scopes": [ |
96 | | - "com.stansassets" |
97 | | - ] |
98 | | - } |
99 | | - ], |
100 | | - "dependencies": { |
101 | | - "com.stansassets.plugins-dev-kit": "file:../../com.stansassets.plugins-dev-kit", |
102 | | -``` |
103 | | - |
104 | | -Note: |
105 | | -* If you are planning to distribute your package via [Git URL](https://docs.unity3d.com/Manual/upm-git.html), this structure would not work for you. In this case, you will need to place your package in the repository root. |
106 | | -* Template `.gitignore` will also ignore project settings. The motivation here, is that you need to ensure that your package will run on different Unity editor versions/configurations and your team members might be jumping between those versions. Adding ProjectSettins into `.gitignore` will help to avoid conflicts between developers. |
107 | | - |
108 | | -## Package Info |
109 | | -You are not obligated to provide any description files with your package, but to be a good citizen it's nice to at least ship the following files for your project. |
110 | | -And you probably want all the links to work when your package is viewed in the [Package Manager window](https://docs.unity3d.com/Manual/upm-ui.html) |
111 | | - |
112 | | - |
113 | | -### LICENSE.md |
114 | | -You should specify a license for your package so that people know how they are permitted to use it, and any restrictions you’re placing on it. |
115 | | -The template repository `LICENSE.md` file already comes the MIT license. |
116 | | - |
117 | | -### CHANGELOG.md |
118 | | -A changelog is a file that contains a curated, chronologically ordered list of notable changes for each version of a project. To make it easier for users and contributors to see precisely what notable changes have been made between each release (or version) of the project. |
119 | | -The template repository `CHANGELOG.md` has some sample records based on [keep a changelog](https://keepachangelog.com/) standard. |
120 | | - |
121 | | -### Documentation~/YourPackageName.md |
122 | | -The fill contains and offline package documentation. I recommend placing the package description and links to the web documentation into that file. |
123 | | - |
124 | | -### README.md |
125 | | -I do not think I have to explain why this is important :) Besides this file will be used to make home page content for your package if you distribute it on [npm](https://www.npmjs.com/) or [openUPM](https://openupm.com/). The template repository `README.md` already contains some content that describes how to install your package via [npm](https://www.npmjs.com/), [openUPM](https://openupm.com/) or [Git URL](https://docs.unity3d.com/Manual/upm-git.html) |
126 | | - |
127 | | -There are also some cool badges you would probably like to use. The [Foundation package](https://github.com/StansAssets/com.stansassets.foundation) is a good example of how it can look like: |
128 | | - |
129 | | - |
130 | | -## Package layout |
131 | | -The repository package layout follows an [official Unity packages convetion](https://docs.unity3d.com/Manual/cus-layout.html). |
132 | | - |
133 | | -``` |
134 | | -<root> |
135 | | - ├── package.json |
136 | | - ├── README.md |
137 | | - ├── CHANGELOG.md |
138 | | - ├── LICENSE.md |
139 | | - ├── Editor |
140 | | - │ ├── Unity.[YourPackageName].Editor.asmdef |
141 | | - │ └── EditorExample.cs |
142 | | - ├── Runtime |
143 | | - │ ├── Unity.[YourPackageName].asmdef |
144 | | - │ └── RuntimeExample.cs |
145 | | - ├── Tests |
146 | | - │ ├── Editor |
147 | | - │ │ ├── Unity.[YourPackageName].Editor.Tests.asmdef |
148 | | - │ │ └── EditorExampleTest.cs |
149 | | - │ └── Runtime |
150 | | - │ ├── Unity.[YourPackageName].Tests.asmdef |
151 | | - │ └── RuntimeExampleTest.cs |
152 | | - └── Documentation~ |
153 | | - └── [YourPackageName].md |
154 | | -``` |
155 | | -The only commend I would like to add if you not using something (for example, you do not have tests atm) or your package does not have Editor API. Please remove unused folders and `*.asmdef` files. |
156 | | -The same if you aren't keeping changelog up to date, then remove the `CHANGELOG.md`. |
157 | | - |
158 | | -Keeping unused & not maintained parts in the published product is misleading for the users, please avoid. |
159 | | - |
160 | | -## CI / CD |
161 | | -It's important to have, it will save your development time. Again this is something I don't have to explain, let's just go straight to what we already have set in this package template repository. |
162 | | - |
163 | | -### Publish to NPM |
164 | | -The action will publish package to npmjs every time the new GitHub release is created. The full article about this action and package distribution and publishing automation can be found [here](https://github.com/StansAssets/com.stansassets.foundation/wiki/Publish-Unity-package-with-NPMJS). |
165 | | -* Action file: **publish-to-npm.yml** |
166 | | -* Setup: |
167 | | - * Update `<your-package-name>` with the package name that needs to be published. |
168 | | - * Add _NPM_TOKEN_ to the reprository Secrets. |
169 | | - |
170 | | -### Assign PR Creator |
171 | | -This GitHub action will assign pull requests to their authors. |
172 | | -* Action file: **assign-pr-creator.yml** |
173 | | -* Setup: not setup actions needed. |
174 | | - |
175 | | -### Automatically Rebase PRs |
176 | | -Simply comment `/rebase` to trigger the action. Read more about rebase action [here](https://github.com/cirrus-actions/rebase) |
177 | | -* Action file: **automatic-rebase.yml** |
178 | | -* Setup: not setup actions needed. |
179 | | - |
180 | | - |
181 | | -### Next Steps |
182 | | -To make me completely happy about this template there should be few more set up steps. But I think we will get to it with the next article. |
183 | | - |
184 | | -* Automatic `CHANGELOG.md` generation. We are already feeling up the release notes, I don't see the reason why we have to do it again the `CHANGELOG.md` when we can simply have an automated commit before publishing to npm action. |
185 | | -* Editor and Playmode tests. It's not a real CI until we have no tests running. |
186 | | -* Docfx + GitHub Pages documentation static website generation. |
| 3 | +[](https://www.npmjs.com/package/com.stansassets.plugins-dev-kit) |
| 4 | +[](https://openupm.com/packages/com.stansassets.plugins-dev-kit/) |
| 5 | +[](https://github.com/StansAssets/com.stansassets.plugins-dev-kit/blob/master/LICENSE) |
| 6 | +[](https://github.com/StansAssets/com.stansassets.plugins-dev-kit/issues) |
0 commit comments