1# 🌀 Contributing to Strudel 🌀
2
3Thanks for wanting to contribute!!! There are many ways you can add value to this project
4
5## Move to codeberg
6
7Along with many other live coding projects, we have moved from Microsoft's Github platform to Codeberg for ethical reasons. Please don't fork the project back to github.
8
9## Communication Channels
10
11To get in touch with the community, either
12
13- [join the Uzulang Discord Server](https://discord.com/invite/HGEdXmRkzT) and go to the strudel channels (Uzulangs are a family of live coding languages inspired by each other, including TidalCycles as well as Strudel)
14- Find related discussions on the [tidal club forum](https://club.tidalcycles.org/)
15
16## Ask a Question
17
18If you have any questions about strudel, make sure you've glanced through the
19[docs](https://strudel.cc/learn/) to find out if it answers your question.
20If not, use one of the Communication Channels above!
21
22Don't be afraid to ask! Your question might be of great value for other people too.
23
24## Give Feedback
25
26No matter if you've used the Strudel REPL or if you are using the strudel packages, we are happy to hear some feedback.
27Use one of the Communication Channels listed above and drop us a line or two!
28
29## Share Music
30
31If you made some music with strudel, you can give back some love and share what you've done!
32Use one of the Communication Channels listed above.
33(There used to be a random selection of contributed patterns in the REPL, but that is unfortunately disabled for now due to abuse)
34
35## Improve the Docs
36
37If you find some weak spots in the [docs](https://strudel.cc/workshop/getting-started/), you can edit each file directly on codeberg. There are "Edit this page" links in the right sidebar that take you to the right place.
38
39## Propose a Feature
40
41If you want a specific feature that is not part of strudel yet, feel free to use one of the communication channels above. Please bear in mind that this is a free/open source project, oriented around collaborative discussion. Maybe you even want to help with the implementation of that feature!
42
43## Contribute a feature
44
45Pull requests welcome! Consider starting with discussion or proof-of-concept first, rather than do loads of work on something and then find it doesn't fit the collective goals of the project, or something like that.
46
47At the time of writing we have a PR backlog, and generally prioritise bugfixes and contributions that have arisen through community discussion.
48
49### AI/LLM policy
50
51Strudel is a project handmade by humans, with thought and nuance. 
52
53If you have used LLMs (so called 'AI'), please detail that in the pull request. We are still developing our response to the onslaught of LLM technology, but for practical and legal reasons are currently not accepting wholly LLM-generated code. We are also not accepting PRs that add LLM features to strudel itself.
54
55There are #llm-chat and #llm-share channels on [our discord](https://discord.com/invite/HGEdXmRkzT). Please do not discuss or share LLM-related things outside of those channels.
56
57## Creating and sharing a new project using strudel
58
59Strudel is free/open source software, and we are also happy to see people making use of it within the following terms. 
60
61Please don't use 'strudel' in the name of your project, so people don't assume it's official strudel project. (If you'd like it to be an official strudel project, please check in with the community, e.g. on [the discord](https://discord.com/invite/HGEdXmRkzT).) 
62
63Please respect our AGPL license, which e.g. requires you to share/link to the source code of strudel, any modifications you've made to it, and the source code for the rest of your project if it integrates with strudel. You are also required to maintain Strudel's copyright notices in the source code, and include Strudel's copyright notice in your user interface. This is an ad-hoc summary - please [refer to the license](https://codeberg.org/uzu/strudel/src/branch/main/LICENSE) for full details.
64
65You are also encouraged to connect with the community and understand our aims and values.
66
67## Report a Bug
68
69If you've found a bug, or some behaviour that does not seem right, you are welcome to file an [issue](https://codeberg.org/uzu/strudel/issues).
70
71Please check that it has not been reported before.
72
73## Fix a Bug
74
75To fix a bug that has been reported,
76
771. check that nobody else is already fixing it and respond to the issue to let people know you're on it
782. fork the repository
793. make sure you've setup the project (see below)
804. hopefully fix the bug
815. make sure the tests pass
826. send a pull request
83
84## Write Tests
85
86There are still many tests that have not been written yet! Reading and writing tests is a great opportunity to get familiar with the codebase.
87You can find the tests in each package in the `test` folder. To run all tests, run `pnpm test` from the root folder.
88
89## Project Setup
90
91To get the project up and running for development, make sure you have installed:
92
93- [git](https://git-scm.com/)
94- [node](https://nodejs.org/en/) >= 18
95- [pnpm](https://pnpm.io/) (`curl -fsSL https://get.pnpm.io/install.sh | env PNPM_VERSION=8.11.0 sh -`)
96
97then, do the following:
98
99```sh
100git clone https://codeberg.org/uzu/strudel.git && cd strudel
101pnpm i # install at root to symlink packages
102pnpm start # start repl
103```
104
105Those commands might look slightly different for your OS.
106Please report any problems you've had with the setup instructions!
107
108## Code Style
109
110To make sure the code changes only where it should, we are using prettier to unify the code style.
111
112- You can format all files at once by running `pnpm codeformat` from the project root
113- Run `pnpm format-check` from the project root to check if all files are well formatted
114
115If you use VSCode, you can
116
1171. install [the prettier extension](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode)
1182. open command palette and run "Format Document With..."
1193. Choose "Configure Default Formatter..."
1204. Select prettier
121
122## ESLint
123
124To prevent unwanted runtime errors, this project uses [eslint](https://eslint.org/).
125
126- You can check for lint errors by running `pnpm lint`
127
128There are also eslint extensions / plugins for most editors.
129
130## Running Tests
131
132- Run all tests with `pnpm test`
133- Run all tests with UI using `pnpm test-ui`
134
135## Running all CI Checks
136
137When opening a PR, the CI runner will (once approved by a human) check the code style and eslint, as well as run all tests. You can run the same check with `pnpm check`.
138
139## Package Workflow
140
141The project is split into multiple [packages](https://codeberg.org/uzu/strudel/src/branch/main/packages) with independent versioning.
142When you run `pnpm i` on the root folder, [pnpm workspaces](https://pnpm.io/workspaces) will install all dependencies of all subpackages. This will allow any js file to import `@strudel/<package-name>` to get the local version,
143allowing to develop multiple packages at the same time.
144
145## Package Publishing
146
147To publish all packages that have been changed since the last release, run:
148
149```sh
150npm login
151
152# this will increment all the versions in package.json files of non private packages to selected versions
153npx lerna version --no-private
154
155# publish all packages inside /packages using pnpm! don't use lerna to publish!!
156pnpm --filter "./packages/**" publish --dry-run
157
158# the last command was only a dry-run. if everything looks ok, run this:
159
160pnpm --filter "./packages/**" publish --access public
161```
162
163To manually publish a single package, increase the version in the `package.json`, then run `pnpm publish`.
164Important: Always publish with `pnpm`, as `npm` does not support overriding main files in `publishConfig`, which is done in all the packages.
165
166
167## useful commands
168
169```sh
170#regenerate the test snapshots (ex: when updating or creating new pattern functions)
171pnpm snapshot 
172
173#start the OSC server
174pnpm run osc
175
176#build the standalone version
177pnpm tauri build
178```
179
180## version tag patching
181
182here's a little guide on how to patch patterns in the database to prevent breaking old patterns due to breaking changes in newer versions.
183
184the general tactic is to use `// @version x.y` to tag a pattern with a specific strudel version. when a pattern is evaluated, this metadata will de-activate any breaking changes that came after the specified version. 
185for example, in version 1.1, the default value for `fanchor` was changed from `0.5` to `0`.
186if play a pattern that was made before that change, sounds that use filter evenlopes can sound very different, so by adding `// @version 1.0` will make it sound like it used to.
187before releasing a new version with breaking changes, we can edit all patterns in the database, inserting the version tag they were created under:
188
189as an example, to release version 1.2, do the following:
190
1911. get date range
192
193```sh
194# get date of last version:
195git log -1 --format=%aI @strudel/core@1.1.0
196# 2024-05-31T23:07:26+02:00
197
198# get date of current version:
199git log -1 --format=%aI @strudel/core@1.2.0
200# 2025-05-01T12:39:24+02:00
201# might also use todays timestamp if version is not yet released
202```
203
204now we know, all patterns between these 2 dates have to receive a version tag (unless they already have one).
205
2062. get patterns in question
207
208```sql
209SELECT *
210FROM code_v1
211WHERE code NOT LIKE '%@version%'
212AND created_at > '2024-05-31T23:07:26+02:00'
213AND created_at < '2025-05-01T12:39:24+02:00'
214ORDER BY created_at ASC;
215```
216
217this gives us all unversioned patterns that were saved between 1.1.0 and 1.2.0. in this case, it's 9373 patterns!
218
2193. insert version tags
220
221we are now ready to insert the version tag to these patterns.
222before updating thousands of patterns, it's probably a good idea to test if a single one gets udpated:
223
224```sql
225UPDATE code_v1
226SET code = code || E'\n// @version 1.1'
227WHERE hash = 'Ns2sMB40yIw4';
228```
229
230after [verifying](https://strudel.cc/?Ns2sMB40yIw4) that the version tag has been added, let's insert it everywhere:
231
232```sql
233UPDATE code_v1
234SET code = code || E'\n// @version 1.1'
235WHERE code NOT LIKE '%@version%'
236AND created_at > '2024-05-31T23:07:26+02:00'
237AND created_at < '2025-05-01T12:39:24+02:00'
238```
239
2404. verify
241
242we can verify that the edits worked by querying all patterns that contain the new version tag:
243
244```sql
245SELECT *
246FROM code_v1
247WHERE code LIKE '%@version 1.1%'
248AND created_at > '2024-05-31T23:07:26+02:00'
249AND created_at < '2025-05-01T12:39:24+02:00'
250ORDER BY created_at ASC;
251```
252
253
254## Have Fun
255
256Remember to have fun, and that this project is driven by the passion of volunteers!