From c030d396af46709ad2db78088c12c060152ff42c Mon Sep 17 00:00:00 2001 From: EncodedVenom <32179912+EncodedVenom@users.noreply.github.com> Date: Sat, 17 May 2025 16:35:00 -0400 Subject: [PATCH 1/2] docs: cleanup todo stubs, add code coverage reports, add examples, and pin introduction section (#227) * Allow pre existing hooks for observer * Cleanup some todo stubs * move coverage reports * use better link for addons * code coverage page * make Introduction sidebar visible on all pages and add a few relevant sections --------- Co-authored-by: Ukendio --- docs/.vitepress/config.mts | 37 +++++++-- docs/contributing/coverage.md | 17 ++++ docs/contributing/guidelines.md | 22 +++++- docs/contributing/issues.md | 26 ++++++- docs/contributing/pull-requests.md | 78 ++++++++++++++++++- docs/learn/concepts/addons.md | 2 +- .../public/coverage}/ansi.luau.html | 0 .../coverage}/entity_visualiser.luau.html | 0 {coverage => docs/public/coverage}/index.html | 0 .../public/coverage}/jecs.luau.html | 0 .../coverage}/lifetime_tracker.luau.html | 0 .../public/coverage}/testkit.luau.html | 0 .../public/coverage}/tests.luau.html | 0 13 files changed, 169 insertions(+), 13 deletions(-) create mode 100644 docs/contributing/coverage.md rename {coverage => docs/public/coverage}/ansi.luau.html (100%) rename {coverage => docs/public/coverage}/entity_visualiser.luau.html (100%) rename {coverage => docs/public/coverage}/index.html (100%) rename {coverage => docs/public/coverage}/jecs.luau.html (100%) rename {coverage => docs/public/coverage}/lifetime_tracker.luau.html (100%) rename {coverage => docs/public/coverage}/testkit.luau.html (100%) rename {coverage => docs/public/coverage}/tests.luau.html (100%) diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts index 537cf76..eb64153 100644 --- a/docs/.vitepress/config.mts +++ b/docs/.vitepress/config.mts @@ -15,6 +15,13 @@ export default defineConfig({ sidebar: { "/api/": [ + { + text: "Introduction", + items: [ + { text: "Getting Started", link: "/learn/overview/get-started" }, + { text: "First Jecs Project", link: "/learn/overview/first-jecs-project" }, + ] + }, { text: "API reference", items: [ @@ -22,7 +29,7 @@ export default defineConfig({ { text: "World", link: "/api/world" }, { text: "Query", link: "/api/query" }, ], - }, + } ], "/learn/": [ { @@ -43,17 +50,35 @@ export default defineConfig({ ], }, { - text: "FAQ", - items: [{ text: "How can I contribute?", link: "/learn/faq/contributing" }], + text: "API Reference", + items: [ + { text: "jecs", link: "/api/jecs"}, + { text: "World", link: "/api/world"}, + { text: "Query", link: "/api/query"} + ] }, + { + text: "Contribute", + items: [ + { text: "How Can I Contribute?", link: "/contributing/guidelines" } + ] + } ], "/contributing/": [ + { + text: "Introduction", + items: [ + { text: "Getting Started", link: "/learn/overview/get-started" }, + { text: "First Jecs Project", link: "/learn/overview/first-jecs-project" }, + ], + }, { text: "Contributing", items: [ - { text: "Contribution Guidelines", link: "/learn/contributing/guidelines" }, - { text: "Submitting Issues", link: "/learn/contributing/issues" }, - { text: "Submitting Pull Requests", link: "/learn/contributing/pull-requests" }, + { text: "Contribution Guidelines", link: "/contributing/guidelines" }, + { text: "Submitting Issues", link: "/contributing/issues" }, + { text: "Submitting Pull Requests", link: "/contributing/pull-requests" }, + { text: "Code Coverage", link: "/contributing/coverage" }, ], }, ], diff --git a/docs/contributing/coverage.md b/docs/contributing/coverage.md new file mode 100644 index 0000000..ea56ccb --- /dev/null +++ b/docs/contributing/coverage.md @@ -0,0 +1,17 @@ +# Code Coverage Reports + +All of the code coverage reports can be found here: + +[Overview](/jecs/coverage/index.html){target="_self"} + +[jecs.luau](/jecs/coverage/jecs.luau.html){target="_self"} + +[ANSI](/jecs/coverage/ansi.luau.html){target="_self"} + +[Entity Visualiser](/jecs/coverage/entity_visualiser.luau.html){target="_self"} + +[Lifetime Tracker](/jecs/coverage/lifetime_tracker.luau.html){target="_self"} + +[Testkit](/jecs/coverage/testkit.luau.html){target="_self"} + +[Tests](/jecs/coverage/tests.luau.html){target="_self"} \ No newline at end of file diff --git a/docs/contributing/guidelines.md b/docs/contributing/guidelines.md index 2e03428..d0e3fcb 100644 --- a/docs/contributing/guidelines.md +++ b/docs/contributing/guidelines.md @@ -1,3 +1,21 @@ -## TODO +# Contribution Guidelines -This is a TODO stub. \ No newline at end of file +Whether you found an issue, or want to make a change to jecs, we'd love to hear back from the community on what features you want or bugs you've run into. + +There's a few different ways you can go about this. + +## Creating an Issue + +This is what you should be filing if you have a bug you want to report. + +[Click here](https://github.com/Ukendio/jecs/issues/new/choose) to file a bug report. We have a few templates ready for the most common issue types. + +Additionally, see the [Submitting Issues](/contributing/issues) page for more information. + +## Creating a Pull Request + +This is what you should be filing if you have a change you want to merge into the main project. + +[Click here](https://github.com/Ukendio/jecs/compare) to select the branch you want to merge from. + +Additionally, see the [Submitting Pull Requests](/contributing/pull-requests) page for more information. \ No newline at end of file diff --git a/docs/contributing/issues.md b/docs/contributing/issues.md index 2e03428..4db8d91 100644 --- a/docs/contributing/issues.md +++ b/docs/contributing/issues.md @@ -1,3 +1,25 @@ -## TODO +# Submitting Issues + +When you're submitting an issue, generally they fall into a few categories: + +## Bug + +We need some information to figure out what's going wrong. At a minimum, you need to tell us: + + (1) What's supposed to happen + + (2) What actually happened + + (3) Steps to reproduce + + +Stack traces and other useful information that you find make a bug report more likely to be fixed. + +Consult the template for a bug report if you don't know or have questions about how to format this. + +## Documentation + +Depending on how you go about it, this can be done as a [Pull Request](/contributing/pull-requests) instead of an issue. Generally, we need to know what was wrong, what you changed, and how it improved the documentation if it isn't obvious. + +We just need to know what's wrong. You should fill out a [PR](/contributing/pull-requests) if you know what should be there instead. -This is a TODO stub. \ No newline at end of file diff --git a/docs/contributing/pull-requests.md b/docs/contributing/pull-requests.md index 2e03428..674e2b0 100644 --- a/docs/contributing/pull-requests.md +++ b/docs/contributing/pull-requests.md @@ -1,3 +1,77 @@ -## TODO +# Submitting Pull Requests -This is a TODO stub. \ No newline at end of file +When submitting a Pull Request, there's a few reasons to do so: + + +## Documentation + +If there's something to change with the documentation, you should follow a similar format to this example: + +An example of an appropriate typo-fixing PR would be: + +>**Brief Description of your Changes** +> +>I fixed a couple of typos found in the /contributing/issues.md file. +> +>**Impact of your Changes** +> +>- Documentation is more clear and readable for the users. +> +>**Tests Performed** +> +>Ran `vitepress dev docs` and verified it was built successfully. +> +>**Additional Comments** +> +>[At Discretion] + +## Change in Behavior + +An example of an appropriate PR that adds a new feature would be: + +> +>**Brief Description of your Changes** +> +>I added `jecs.best_function`, which gives everyone who uses the module an immediate boost in concurrent player counts. (this is a joke) +> +>**Impact of your Changes** +> +>- jecs functionality is extended to better fit the needs of the community [explain why]. +> +>**Tests Performed** +> +>Added a few test cases to ensure the function runs as expected [link to changes]. +> +>**Additional Comments** +> +>[At Discretion] + +## Addons + +If you made something you think should be included into the [addons page](/learn/concepts/addons), let us know! + +We have tons of examples of libraries and other tools which can be used in conjunction with jecs on this page. + +One example of a PR that would be accepted is: + +>**Brief Description of your Changes** +> +>I added [jecs observers](/learn/concepts/addons#jecs_observers) to the addons page. +> +>**Impact of your Changes** +> +>- jecs observers are a different and important way of handling queries which benefit the users of jecs by [explain why your tool benefits users here] +> +>- [talk about why you went with this design instead of maybe an alternative] +> +>**Tests Performed** +> +> I used this tool in conjunction with jecs and ensured it works as expected. +> +> [If you wrote unit tests for your tool, mention it here.] +> +>**Additional Comments** +> +>[At Discretion] + +Keep in mind the list on the addons page is *not* exhaustive. If you came up with a tool that doesn't fit into any of the categories listed, we still want to hear from you! \ No newline at end of file diff --git a/docs/learn/concepts/addons.md b/docs/learn/concepts/addons.md index 769baa9..8274c2f 100644 --- a/docs/learn/concepts/addons.md +++ b/docs/learn/concepts/addons.md @@ -1,6 +1,6 @@ # Addons -A collection of third-party jecs addons made by the community. If you would like to share what you're working on, [submit a pull request](https://github.com/Ukendio/jecs)! +A collection of third-party jecs addons made by the community. If you would like to share what you're working on, [submit a pull request](/contributing/pull-requests#addons)! # Development tools diff --git a/coverage/ansi.luau.html b/docs/public/coverage/ansi.luau.html similarity index 100% rename from coverage/ansi.luau.html rename to docs/public/coverage/ansi.luau.html diff --git a/coverage/entity_visualiser.luau.html b/docs/public/coverage/entity_visualiser.luau.html similarity index 100% rename from coverage/entity_visualiser.luau.html rename to docs/public/coverage/entity_visualiser.luau.html diff --git a/coverage/index.html b/docs/public/coverage/index.html similarity index 100% rename from coverage/index.html rename to docs/public/coverage/index.html diff --git a/coverage/jecs.luau.html b/docs/public/coverage/jecs.luau.html similarity index 100% rename from coverage/jecs.luau.html rename to docs/public/coverage/jecs.luau.html diff --git a/coverage/lifetime_tracker.luau.html b/docs/public/coverage/lifetime_tracker.luau.html similarity index 100% rename from coverage/lifetime_tracker.luau.html rename to docs/public/coverage/lifetime_tracker.luau.html diff --git a/coverage/testkit.luau.html b/docs/public/coverage/testkit.luau.html similarity index 100% rename from coverage/testkit.luau.html rename to docs/public/coverage/testkit.luau.html diff --git a/coverage/tests.luau.html b/docs/public/coverage/tests.luau.html similarity index 100% rename from coverage/tests.luau.html rename to docs/public/coverage/tests.luau.html From 22877f3fc5394d14b0b71659eda0ddf9341b967e Mon Sep 17 00:00:00 2001 From: Junjie <138041510+NormalDuck@users.noreply.github.com> Date: Sat, 17 May 2025 16:44:22 -0700 Subject: [PATCH 2/2] Allow world.add() to accept component, add world.entity overload (#225) * fix: allow components for world.add in typescript * fix: add overload for world.entity * build: downgrade deps to v0.6.0 * fix: world.entity accepts entity instead of number * fix: allow union undefined union to be passed in .add --- jecs.d.ts | 3 ++- package-lock.json | 4 ++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/jecs.d.ts b/jecs.d.ts index 01239fd..6047d30 100644 --- a/jecs.d.ts +++ b/jecs.d.ts @@ -120,6 +120,7 @@ export class World { * @returns An entity (Tag) with no data. */ entity(): Tag; + entity(id: T): InferComponent extends undefined ? Tag : T; /** * Creates a new entity in the first 256 IDs, typically used for static @@ -148,7 +149,7 @@ export class World { * @param entity The target entity. * @param component The component (or tag) to add. */ - add(entity: Entity, component: Id): void; + add(entity: Entity, component: undefined extends InferComponent ? C : Id): void; /** * Assigns a value to a component on the given entity. diff --git a/package-lock.json b/package-lock.json index ba8032d..ee2861d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@rbxts/jecs", - "version": "0.6.0-rc.1", + "version": "0.6.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@rbxts/jecs", - "version": "0.6.0-rc.1", + "version": "0.6.0", "license": "MIT", "devDependencies": { "@rbxts/compiler-types": "^2.3.0-types.1",