You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# Objective
- the plugin guidelines should be up-to-date and easy to read/understand
## Solution
* point to "Bevy Assets" instead of old "Awesome Bevy"
* restructure sections
* same order for sections and checklist
* Update examples with newest release/rev
*[ ][Publish your plugin](#publishing-your-plugin)
18
17
*[ ][Promote your plugin](#promotion)
19
18
20
19
## Naming
21
20
22
21
You are free to use a `bevy_xxx` name for your plugin, but please be reasonable. If you are about to claim a generic name like `bevy_animation`, `bevy_color`, or `bevy_editor`, please ask first. The rationale is explained [here](https://github.com/bevyengine/bevy/discussions/1202#discussioncomment-258907).
23
22
24
-
## Promotion
25
-
26
-
You can promote your plugin in Bevy's [communities](https://github.com/bevyengine/bevy#community):
27
-
28
-
* Add it to [Awesome Bevy](https://github.com/bevyengine/awesome-bevy).
29
-
* Announce it on [Discord](https://discord.gg/bevy), in the `#showcase` channel.
30
-
* Announce it on [Reddit](https://reddit.com/r/bevy).
31
-
32
-
## Bevy Version Supported
33
-
34
-
Indicating which version of your plugin works with which version of Bevy can be helpful for your users. Some of your users may be using an older version of Bevy for any number of reasons. You can help them find which version of your plugin they should use. This can be shown as a simple table in your readme with each version of Bevy and the corresponding compatible version of your plugin.
35
-
36
-
|bevy|bevy_awesome_plugin|
37
-
|---|---|
38
-
|0.4|0.3|
39
-
|0.3|0.1|
40
-
41
-
## Bevy Features
42
-
43
-
You should disable Bevy features that you don't use. This is because with Cargo, features are additive. Features that are enabled for Bevy in your plugin can't be disabled by someone using your plugin. You can find the list of features [here](cargo_features.md).
44
-
45
-
```toml
46
-
bevy = { version = "0.4", default-features = false, features = ["..."] }
47
-
```
48
-
49
23
## Main Branch Tracking
50
24
25
+
Bevy is evolving very fast. Regularly new features are working on the main branch, but are not yet released. Your plugin might depend on Bevy main or the latest release. You can also do both on different branches (e.g. have a `bevy_main` branch).
26
+
51
27
If you intend to track Bevy's main branch, you can specify the latest commit you support in your `Cargo.toml` file:
You can specify the dependency [both as a version and with git](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#multiple-locations), the version will be used if using the dependency from [crates.io](https://crates.io), the git dependency will be used otherwise.
33
+
You can specify the dependency [both as a version and with git](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#multiple-locations). The version will be used if the dependency is pulled from [crates.io](https://crates.io). Otherwise, the git dependency will be used.
58
34
59
-
Bevy is evolving very fast. You can use one of these badges to communicate to your users how closely you intend to track Bevy's main branch.
35
+
You can use one of these badges to communicate to your users how closely you intend to track Bevy's main branch.
60
36
61
37
<!-- MD033 - The Badges could be downsized, without the inline HTML due to the large code colum -->
62
38
<!-- markdownlint-disable-next-line MD033 -->
@@ -65,42 +41,54 @@ Bevy is evolving very fast. You can use one of these badges to communicate to yo
65
41
|[](https://github.com/bevyengine/bevy/blob/main/docs/plugins_guidelines.md#main-branch-tracking)|I intend to track main as much as I can|`[](https://github.com/bevyengine/bevy/blob/main/docs/plugins_guidelines.md#main-branch-tracking)`|
66
42
|[](https://github.com/bevyengine/bevy/blob/main/docs/plugins_guidelines.md#main-branch-tracking)|I will only follow released Bevy versions|`[](https://github.com/bevyengine/bevy/blob/main/docs/plugins_guidelines.md#main-branch-tracking)`|
67
43
68
-
## General Advices for a Rust Crate
69
-
70
-
This advice is valid for any Rust crate.
44
+
## Licensing
71
45
72
-
### Licensing
73
-
74
-
Bevy is dual licensed under [MIT or Apache 2.0](https://www.rust-lang.org/policies/licenses), at your option. Most other Rust projects (including Rust itself) also use this dual-license approach. MIT-only is very popular and you might be tempted to just use that (Bevy also used to be MIT-only), but there are [very good reasons](https://github.com/bevyengine/bevy/issues/2373) to include both and we highly recommend using the dual MIT / Apache-2.0 license for your Bevy Plugins and crates:
46
+
Bevy is dual licensed under [MIT or Apache 2.0](https://www.rust-lang.org/policies/licenses), at your option. Most other Rust projects (including Rust itself) also use this dual-license approach. MIT-only is very popular and you might be tempted to just use that (Bevy also used to be MIT-only), but there are [very good reasons](https://github.com/bevyengine/bevy/issues/2373) to include both licenses. We highly recommend using the dual MIT / Apache-2.0 license for your Bevy Plugins and crates:
75
47
76
48
* Including the Apache 2.0 license option significantly reduces the difficulty and boilerplate of proper license compliance in published games because you only need to include one copy of the Apache 2.0 license.
77
49
* Provides maximum compatibility with Bevy and Rust, making it easier to upstream your changes.
78
50
79
-
###Small Crate Size
51
+
## Small Crate Size
80
52
81
-
To avoid long build times in your crate and in projects using your plugin, you should aim for a small crate size:
53
+
To avoid long build times in your plugin and in projects using it, you should aim for a small crate size:
82
54
83
55
* Disable Bevy features that you don't use
56
+
* Features are additive => Bevy features enabled in your plugin cannot be disabled by someone using your plugin
57
+
* You can find Bevy's features [here](cargo_features.md).
58
+
59
+
```toml
60
+
bevy = { version = "0.5", default-features = false, features = ["..."] }
61
+
```
62
+
84
63
* Avoid large dependencies
85
64
* Put optional functionality and dependencies behind a feature
86
65
87
-
###Documentation and Examples
66
+
## Documentation and Examples
88
67
89
68
Documentation and examples are very useful for a crate.
90
69
91
-
In the case of a plugin for Bevy, a few screenshots or movies/animated GIFs from your examples can really help understanding what your plugin can do.
70
+
In the case of a Bevy plugin, a few screenshots or movies/animated GIFs from your examples can really help to understand what your plugin is capable of.
92
71
93
72
Additionally, it can be helpful to list:
94
73
95
74
* Stages added by the plugin
96
75
* Systems used
97
-
*New components available
76
+
* Components available from your plugin
98
77
99
-
### Tests and CI
78
+
### Indicate Compatible Versions
100
79
101
-
Tests are always good! For CI, you can check [this example](https://github.com/actions-rs/meta/blob/master/recipes/quickstart.md) for a quickstart using GitHub Actions. As Bevy has additional Linux dependencies, you should install them before building your project, [here is how Bevy is doing it](https://github.com/bevyengine/bevy/blob/cf0e9f9968bb1bceb92a61cd773478675d35cbd6/.github/workflows/ci.yml#L39). Even if you don't have many (or any) tests, setting up CI will compile check your plugin and ensure a basic level of quality.
80
+
Indicating which version of your plugin works with which version of Bevy can be helpful for your users. Some of your users may be using an older version of Bevy for any number of reasons. You can help them find which version of your plugin they should use. This can be shown as a simple table in your readme with each version of Bevy and the corresponding compatible version of your plugin.
102
81
103
-
### Publishing your Plugin
82
+
|bevy|bevy_awesome_plugin|
83
+
|---|---|
84
+
|0.5|0.3|
85
+
|0.4|0.1|
86
+
87
+
## Tests and CI
88
+
89
+
Tests are always good! For CI, you can check [this example](https://github.com/actions-rs/meta/blob/master/recipes/quickstart.md) for a quickstart using GitHub Actions. As Bevy has additional Linux dependencies, you should install them before building your project ([here is how Bevy is doing it](https://github.com/bevyengine/bevy/blob/9788b386c7846c99978ab5c1a33698ec5a471d84/.github/workflows/ci.yml#L40)). Even if you don't have many (or any) tests, setting up CI will compile check your plugin and ensure a basic level of quality.
90
+
91
+
## Publishing your Plugin
104
92
105
93
There are some [extra fields](https://doc.rust-lang.org/cargo/reference/manifest.html) that you can add to your `Cargo.toml` manifest, in the `[package]` section:
106
94
@@ -119,3 +107,11 @@ Once a crate is published to [crates.io](https://crates.io), there are two badge
0 commit comments