mirror of
https://git.minetest.land/VoxeLibre/VoxeLibre.git
synced 2024-11-04 23:31:05 +01:00
317 lines
13 KiB
Markdown
317 lines
13 KiB
Markdown
# Contributing to MineClone2
|
|
So you want to contribute to MineClone2?
|
|
Wow, thank you! :-)
|
|
|
|
But first, some things to note:
|
|
|
|
MineClone2's development target is to...
|
|
|
|
- Crucially, create a stable, moddable, free/libre clone of Minecraft
|
|
based on the Minetest engine with polished features, usable in both
|
|
singleplayer and multiplayer. Currently, most of **Minecraft Java
|
|
Edition 1.12.2** features are already implemented and polishing existing
|
|
features are prioritised over new feature requests.
|
|
- With lessened priority yet strictly, implement features targetting
|
|
**Minecraft version 1.17 + Optifine** (Optifine only as far as supported
|
|
by the Minetest Engine). This means features in parity with the listed
|
|
Minecraft experiences are prioritised over those that don't fulfill this
|
|
scope.
|
|
- Optionally, create a performant experience that will run relatively
|
|
well on really low spec computers. Unfortunately, due to Minecraft's
|
|
mechanisms and Minetest engine's limitations along with a very small
|
|
playerbase on low spec computers, optimizations are hard to investigate.
|
|
|
|
MineClone2 is maintained by Nicu and Fleckenstein. If you have any
|
|
problems or questions, contact us (See Links section below).
|
|
|
|
You can help with MineClone2's development in many different ways,
|
|
whether you're a programmer or not.
|
|
|
|
## Links
|
|
* [Mesehub](https://git.minetest.land/MineClone2/MineClone2)
|
|
* [Discord](https://discord.gg/xE4z8EEpDC)
|
|
* [YouTube](https://www.youtube.com/channel/UClI_YcsXMF3KNeJtoBfnk9A)
|
|
* [IRC](https://web.libera.chat/#mineclone2)
|
|
* [Matrix](https://app.element.io/#/room/#mc2:matrix.org)
|
|
* [Reddit](https://www.reddit.com/r/MineClone2/)
|
|
* [Minetest forums](https://forum.minetest.net/viewtopic.php?f=50&t=16407)
|
|
|
|
## Using git
|
|
MineClone2 is developed using the version control system
|
|
[git](https://git-scm.com/). If you want to contribute code to the
|
|
project, it is **highly recommended** that you learn the git basics.
|
|
For non-programmers and people who do not plan to contribute code to
|
|
Mineclone2, git is not required. However, git is a tool that will be
|
|
referenced frequently because of its usefulness. As such, it is valuable
|
|
in learning how git works and its terminology. It can also help you in
|
|
keeping your game updated, and easily testing pull requests.
|
|
|
|
## How you can help as a non-programmer
|
|
|
|
As someone who does not know how to write programs in Lua or does not
|
|
know how to use the Minetest API, you can still help us out a lot. For
|
|
example, by opening an issue in the
|
|
[Issue tracker](https://git.minetest.land/MineClone2/MineClone2/issues),
|
|
you can report a bug or request a feature.
|
|
|
|
### Rules about both bugs and feature requests
|
|
* Stay polite towards the developers and anyone else involved in the
|
|
discussion.
|
|
* Choose a descriptive title.
|
|
* Please write in plain, understandable English. It will be easier to
|
|
communicate.
|
|
* Please start the issue title with a capital letter.
|
|
* Always check the currently opened issues before creating a new one.
|
|
Don't report bugs that have already been reported or request features
|
|
that already have been requested.
|
|
* If you know about Minetest's inner workings, please think about
|
|
whether the bug / the feature that you are reporting / requesting is
|
|
actually an issue with Minetest itself, and if it is, head to the
|
|
[Minetest issue tracker](https://github.com/minetest/minetest/issues)
|
|
instead.
|
|
* If you need any help regarding creating a Mesehub account or opening
|
|
an issue, feel free to ask on the Discord / Matrix server or the IRC
|
|
channel.
|
|
|
|
### Reporting bugs
|
|
* A bug is an unintended behavior or, in the worst case, a crash.
|
|
However, it is not a bug if you believe something is missing in the
|
|
game. In this case, please read "Requesting features"
|
|
* If you report a crash, always include the error message. If you play
|
|
in singleplayer, post a screenshot of the message that minetest showed
|
|
when the crash happened (or copy the message into your issue). If you
|
|
are a server admin, you can find error messages in the log file of the
|
|
server.
|
|
* Tell us which MineClone2 and minetest versions you are using.
|
|
* Tell us how to reproduce the problem: What you were doing to trigger
|
|
the bug, e.g. before the crash happened or what causes the faulty
|
|
behavior.
|
|
|
|
### Requesting features
|
|
* Make sure the feature you request is Minecraft 1.17 Java Edition or
|
|
Optifine behavior.
|
|
* Begging or excessive attention seeking does not help us in the
|
|
slightest, and may very well disrupt Mineclone2 development. It's better
|
|
to put that energy into helping or researching the feature in question.
|
|
After all, we're just volunteers working on our spare time.
|
|
* Check whether the feature has been implemented in a newer version of
|
|
MineClone2, in case you are not using the latest one.
|
|
|
|
### Testing code
|
|
If you want to help us with speeding up MineClone2 development and
|
|
making the game more stable, a great way to do that is by testing out
|
|
new features from contributors. For most new things that get into the
|
|
game, a pull request is created. A pull request is essentially a
|
|
programmer saying "Look, I modified the game, please apply my changes
|
|
to the upstream version of the game". However, every programmer makes
|
|
mistakes sometimes, some of which are hard to spot. You can help by
|
|
downloading this modified version of the game and trying it out - then
|
|
you tell us whether the code works and does what it claims to do or
|
|
whether you have encountered any issues. You can find currently open
|
|
pull requests here:
|
|
<https://git.minetest.land/MineClone2/MineClone2/pulls>. Note that pull
|
|
requests that start with a `WIP:` are not done yet, and therefore might
|
|
not work, so it's not very useful to try them out yet.
|
|
|
|
### Profiling
|
|
If you own a server, a great way to help us improve MineClone2's code
|
|
is by giving us profiler results. Profiler results give us detailed
|
|
information about the game's performance and let us know where the real
|
|
troublespots are. This way we can make the game faster. Minetest has a
|
|
built in profiler. Simply set `profiler.load = true` in your
|
|
configuration file and restart the server. After running the server for
|
|
some time, just run `/profiler save` in chat - then you will find a file
|
|
in the world directory containing the results. Open a new issue and
|
|
upload the file. You can name the issue "<Server name> profiler
|
|
results".
|
|
|
|
### Let us know your opinion
|
|
It is always encouraged to actively contribute to issue discussions on
|
|
MeseHub, let us know what you think about a topic and help us make
|
|
decisions. Also, note that a lot of discussion takes place on the
|
|
Discord server, so it's definitely worth checking it out.
|
|
|
|
### Crediting
|
|
If you opened or have contributed to an issue, you receive the
|
|
`Community` role on our Discord (after asking for it).
|
|
|
|
## How you can help as a programmer
|
|
(Almost) all the MineClone2 development is done using pull requests.
|
|
If you feel like a problem needs to fixed or you want to make a new
|
|
feature, you could start writing the code right away and notifying us
|
|
when you're done, but it never hurts to discuss things first. If there
|
|
is no issue on the topic, open one. If there is an issue, tell us that
|
|
you'd like to take care of it, to avoid duplicate work. We appreciate
|
|
any contributing effort to Mineclone2. If you are a relatively new
|
|
programmer, you can reach us on Discord, Matrix or IRC for questions
|
|
about git, Lua, Minetest API, Mineclone2 codebase or anything related
|
|
to MineClone2. We can help you avoid writing code that would be deemed
|
|
inadequeate, or help you become familiar with Mineclone2 better, or even
|
|
help using development tools. By asking us to include your changes in
|
|
this game, you agree that they fall under the terms of the GPLv3, which
|
|
basically means they will become part of a free software. Sometimes,
|
|
your code may cause crashes or bugs - we try to avoid such scenarios by
|
|
testing everytime before merging it, but if your merged work causes
|
|
problems, we ask you fix the issues as soon as possible.
|
|
|
|
### The recommended workflow
|
|
* Fork the repository (in case you have not already)
|
|
* Do your change in a new branch
|
|
* Create a pull request to get your changes merged into master
|
|
* Keep your pull request up to date by regulary merging upstream. It is
|
|
imperative that conflicts are resolved prior to merging the pull
|
|
request.
|
|
* After the pull request got merged, you can delete the branch
|
|
|
|
### Git Guidelines
|
|
* We use merge rather than rebase or squash merge
|
|
* We don't use git submodules.
|
|
* Your commit names should be relatively descriptive, e.g. when saying
|
|
"Fix #issueid", the commit message should also contain the title of the
|
|
issue.
|
|
* Try to keep your commits as atomic as possible (advise, but completely
|
|
optional)
|
|
|
|
### Code Guidelines
|
|
* Each mod must provide `mod.conf`.
|
|
* Mod names are snake case, and newly added mods start with `mcl_`, e.g.
|
|
`mcl_core`, `mcl_farming`, `mcl_monster_eggs`. Keep in mind Minetest
|
|
does not support capital letters in mod names.
|
|
* To export functions, store them inside a global table named like the
|
|
mod, e.g.
|
|
|
|
```lua
|
|
mcl_example = {}
|
|
|
|
function mcl_example.do_something()
|
|
-- ...
|
|
end
|
|
|
|
```
|
|
|
|
* Public functions should not use self references but rather just access
|
|
the table directly, e.g.
|
|
|
|
```lua
|
|
-- bad
|
|
function mcl_example:do_something()
|
|
end
|
|
|
|
-- good
|
|
function mcl_example.do_something()
|
|
end
|
|
```
|
|
|
|
* Use modern Minetest API, e.g. no usage of `minetest.env`
|
|
* Tabs should be used for indent, spaces for alignment, e.g.
|
|
|
|
```lua
|
|
|
|
-- use tabs for indent
|
|
|
|
for i = 1, 10 do
|
|
if i % 3 == 0 then
|
|
print(i)
|
|
end
|
|
end
|
|
|
|
-- use tabs for indent and spaces to align things
|
|
|
|
some_table = {
|
|
{"a string", 5},
|
|
{"a very much longer string", 10},
|
|
}
|
|
```
|
|
|
|
* Use double quotes for strings, e.g. `"asdf"` rather than `'asdf'`
|
|
* Use snake_case rather than CamelCase, e.g. `my_function` rather than
|
|
`MyFunction`
|
|
* Dont declare functions as an assignment, e.g.
|
|
|
|
```lua
|
|
-- bad
|
|
local some_local_func = function()
|
|
-- ...
|
|
end
|
|
|
|
my_mod.some_func = function()
|
|
-- ...
|
|
end
|
|
|
|
-- good
|
|
local function some_local_func()
|
|
-- ...
|
|
end
|
|
|
|
function my_mod.some_func()
|
|
-- ...
|
|
end
|
|
```
|
|
|
|
### Changes to Gameplay
|
|
Pull Requests that change gameplay have to be properly researched and
|
|
need to state their sources. These PRs also need Fleckenstein's approval
|
|
before they are merged.
|
|
You can use these sources:
|
|
|
|
* Minecraft code (Name the source file and line, however DONT post any
|
|
proprietary code). You can use
|
|
[MCP](https://minecraft.fandom.com/wiki/Programs_and_editors/Mod_Coder_Pack)
|
|
to decompile Minecraft or look at
|
|
[Minestorm](https://github.com/Minestom/Minestom) code.
|
|
* Testing things inside of Minecraft (Attach screenshots / video footage
|
|
of the results)
|
|
* [Official Minecraft Wiki](https://minecraft.fandom.com/wiki/Minecraft_Wiki)
|
|
(Include a link to the specific page you used)
|
|
|
|
### Developer status
|
|
Active and trusted contributors are often granted write access to the
|
|
MineClone2 repository. However you should not push things directly to
|
|
MineClone2 master - rather, do your work on a branch on your private
|
|
repo, then create a pull request. This way other people can review your
|
|
changes and make sure they work before they get merged. You are allowed
|
|
to merge PRs if they have recieved the necessary feedback and have been
|
|
tested to not lead to any crashes and do what they claim to do by at
|
|
least two different people. You may also be assigned to issues or pull
|
|
requests as a developer. In this case it is your responsibility to fix
|
|
the issue / review and merge the pull request when it is ready. You can
|
|
also unassign yourself from the issue / PR if you have no time or don't
|
|
want to take care of it for some other reason (after all, everyone is a
|
|
volunteer and we can't expect you to do work that you are not intrested
|
|
in) - the important thing is really that you make sure to inform us if
|
|
you won't take care of something that has been assigned to you. Also,
|
|
please assign yourself to something that you want to work on to avoid
|
|
duplicate work. As a developer, it should be easy to reach you about
|
|
your code. You should be on the Discord (or, if you really don't like
|
|
Discord, Matrix or IRC).
|
|
|
|
### Maintainer status
|
|
Maintainers are responsible for making sure issues are addressed and
|
|
pull requests are reviewed and merged, by assigning either themselves or
|
|
Developers to issues / PRs. Maintainers are responsible for making
|
|
releases, making sure guidelines are kept and making project decisions
|
|
based on what the community wants. Maintainers grant/revoke developer
|
|
access. Currently there are two maintainers with different
|
|
responsibility fields:
|
|
|
|
* Fleckenstein - responsible for gameplay review, publishing releases,
|
|
technical guidelines and issue/PR delegation
|
|
* Nicu - responsible for community related issues
|
|
|
|
#### Creating releases
|
|
* Launch MineClone2 to make sure it still runs
|
|
* Update the version number in README.md
|
|
* Use `git tag <version number>` to tag the latest commit with the
|
|
version number
|
|
* Push to repo (don't forget `--tags`!)
|
|
* Update ContentDB
|
|
(https://content.minetest.net/packages/Wuzzy/mineclone2/)
|
|
* Update first post in forum thread
|
|
(https://forum.minetest.net/viewtopic.php?f=50&t=16407)
|
|
* Post release announcement and changelog in forums
|
|
|
|
### Crediting
|
|
Contributors, Developers and Maintainers will be credited in
|
|
`CREDITS.md`. If you make your first time contribution, please add
|
|
yourself to this file. There are also Discord roles for Contributors,
|
|
Developers and Maintainers.
|