Skip to content

Commit 6e59b95

Browse files
AlexStormwoodAlexStormwood
committed
Added documentation
1 parent db8cc04 commit 6e59b95

1 file changed

Lines changed: 131 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 131 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,132 @@
1-
# UnityUPMSemver
1+
# Unity UPM Semver
22
Github Action to handle automated semver modification for Unity UPM packages.
3+
4+
## Inputs
5+
6+
This is the data that you must set up in your own workflow file to use this action properly.
7+
8+
### semver-update-type
9+
10+
When calling this action, you can specify the type of semver update you'd like to perform. Suitable values are:
11+
12+
* major - This increments the first number in a "major.minor.patch" version string
13+
* minor - This increments the second number in a "major.minor.patch" version string
14+
* patch - This increments the third number in a "major.minor.patch" version string
15+
16+
### upm-package-directory
17+
18+
When calling this action, you MUST specify the directory that contains your UPM package & its package.json file. If this directory is incorrectly set, the action will fail.
19+
20+
For example, with `steps` code like this in your Github Actions workflow file:
21+
22+
```yaml
23+
- name: Checkout "UPM" branch
24+
uses: actions/checkout@v2
25+
with:
26+
ref: upm
27+
28+
- name: Find UPM package.json & increment its version number
29+
uses: AlexHolderDeveloper/UnityUPMSemver@v0.0.1 # Change vX.X.X to whatever tag is newer in the AlexHolderDeveloper/UnityUPMSemver repository.
30+
id: semver-update-upm
31+
with:
32+
semver-update-type: 'patch' # Change this string to any suitable string mentioned in the Inputs section of this action's readme to suit your needs.
33+
upm-package-directory: '/'
34+
35+
```
36+
37+
The branch "upm" [shown is from this repository](https://github.com/AlexHolderDeveloper/BigfootUnityUtilities/tree/upm). It has its `package.json` file in its root. This means that the `upm-package-directory` value can just be a '/'.
38+
39+
Comparison of paths:
40+
41+
* If at a root directory (eg. the "upm" branch [shown here](https://github.com/AlexHolderDeveloper/BigfootUnityUtilities/tree/upm)): /
42+
43+
* If inside a nested folder inside the repository (eg. the master branch [shown here](https://github.com/AlexHolderDeveloper/BigfootUnityUtilities)): `BigfootUnityUtilities/blob/master/Assets/BigfootDS/BigfootUnityUtilities/`
44+
45+
46+
47+
## Outputs
48+
49+
This is the data that you can use after this action has completed, in other actions & scripts.
50+
51+
### semver-number
52+
53+
This represents the semantic version string _after_ this action has been performed - it will reflect the new, updated version string.
54+
55+
56+
57+
## Example Usage
58+
59+
In your repository containing a Unity project, you should have a Github Actions workflow file set up in your `.github/workflows` directory. Name it whatever you want (as long as it ends in ".yml"!). After letting this action run, you then have to sort out committing & pushing the changed file(s) to your repo from within the workflow. The example code below shows all of this; it updates the patch number in every push made to the repository.
60+
61+
Currently, the big downside to this process is that all developers working on the repo must then fetch & pull the changes made by this action. If you or your developers are editing the `package.json` file of your UPM package manually, you may end up with merge conflicts.
62+
63+
The workflow below shows an example of updating the `package.json` file's `version` property on push. It does this to both a UPM branch (because [the example repo](https://github.com/AlexHolderDeveloper/BigfootUnityUtilities) has its UPM package hosted in a specific branch for usage by others in their own Unity projects) and it the master/main branch (for package maintenance & development).
64+
65+
```yaml
66+
67+
68+
name: Update Unity UPM semantic versioning
69+
70+
on: [push]
71+
72+
jobs:
73+
create:
74+
name: Update semver in UPM package & project settings
75+
runs-on: ubuntu-latest
76+
77+
steps:
78+
# You must ALWAYS checkout your repo so that actions in the workflow can use it.
79+
- name: Checkout "UPM" branch
80+
uses: actions/checkout@v2
81+
with:
82+
ref: upm
83+
84+
- name: Find UPM package.json & increment its version number
85+
uses: AlexHolderDeveloper/UnityUPMSemver@v0.0.1 # Change vX.X.X to whatever tag is newer in the AlexHolderDeveloper/UnityUPMSemver repository.
86+
id: semver-update-upm
87+
with:
88+
semver-update-type: 'patch' # Change this string to any suitable string mentioned in the Inputs section of this action's readme to suit your needs.
89+
upm-package-directory: '/'
90+
91+
# Validate that the number has been incremented correctly.
92+
- name: Get the new semver number
93+
run: echo "The new semver number for this Unity project is ${{ steps.semver-update-upm.outputs.semver-number }}"
94+
95+
# Commit & push the updated semver number back into the repo. Yes, you have to fetch & pull in your local workstation after this step is done.
96+
- name: Push changed files back to repo
97+
uses: stefanzweifel/git-auto-commit-action@v4
98+
with:
99+
commit_message: "Updated semver via automated action."
100+
commit_options: '--no-verify --signoff'
101+
branch: upm
102+
103+
# You must ALWAYS checkout your repo so that actions in the workflow can use it.
104+
- name: Checkout "master" branch
105+
uses: actions/checkout@v2
106+
107+
108+
- name: Find UPM package.json & increment its version number
109+
uses: AlexHolderDeveloper/UnityUPMSemver@v0.0.1 # Change vX.X.X to whatever tag is newer in the AlexHolderDeveloper/UnityUPMSemver repository.
110+
id: semver-update-master
111+
with:
112+
semver-update-type: 'patch' # Change this string to any suitable string mentioned in the Inputs section of this action's readme to suit your needs.
113+
upm-package-directory: '/Assets/BigfootDS/BigfootUnityUtilities/'
114+
115+
# Validate that the number has been incremented correctly.
116+
- name: Get the new semver number
117+
run: echo "The new semver number for this Unity project is ${{ steps.semver-update-master.outputs.semver-number }}"
118+
119+
# Commit & push the updated semver number back into the repo. Yes, you have to fetch & pull in your local workstation after this step is done.
120+
- name: Push changed files back to repo
121+
uses: stefanzweifel/git-auto-commit-action@v4
122+
with:
123+
commit_message: "Updated semver via automated action."
124+
commit_options: '--no-verify --signoff'
125+
branch: master
126+
127+
```
128+
129+
## To-Do List
130+
131+
* General code optimizations
132+
* Create more example workflows

0 commit comments

Comments
 (0)