keturn
New Member
It's easy to overestimate how much we can get done in a week. We're excited by the potential of our ideas, and we want to see a lot of them brought to life! "They're just little things," we think, "that one won't take long."
Keep in mind that even a little feature can have a lot of steps:
Design
Sketch out how it looks, what it will do, how people will interact with it. How it relates to the rest of the system.
Discuss this with stakeholders, incorporate feedback.
You will have already done some of this in the act of writing your proposal, but chances are high that between April and June you will have had a chance to refine these ideas and thought of more questions to ask and met more people to talk to about them. That all means some of your time will likely spent re-visiting your designs.
Research
If you haven't worked in this area of the project recently, it will take you some time to become familiar with the relevant interfaces and terminology.
Whenever you switch between different types of features—e.g. terrain generation, user interface, entity behavior, different game modes—you'll be introduced to a new part of the system. Don't forget to account for that transition time if you propose working in multiple areas.
(Have you counted how many classes there are in Terasology? Sure, they're not all public, but how many of them are? How many more are currently in the modules that your project will be working with?)
Media Assets
Adding an new type of object to the world? It may need
If you're not creating an asset, where will it come from? You may be able to take advantage of existing third-party assets, but
⚠ to include any content in Terasology we must have an appropriate license for it. ⚠
Is there any conversion necessary between the format it is published in and the format the game can load?
Implementation
Write the classes and methods that implement the logic the feature requires. If you're joining us from a curriculum focused around individual programming exercises, this is the part that likely first came to mind when thinking about how long it will take to write a feature.
Testing
Most code benefits from automated tests to help give you confidence that what you're building is behaving correctly, and things continue to behave correctly as you or others make changes. Terasology has test suites with both unit tests and integration tests. Plan to write tests as you go, not as a separate deliverable at the end.
You may find some things impractical to write automated tests for. For those cases, keep notes in your pull request about the things that testers and reviewers should look for when they run your branch.
Things to confirm after you get an initial proof of concept working:
Debugging
You've written enough code to have some idea of how long it takes you to get something you've written to work as intended. That's a normal part of implementation and testing.
I bring up debugging in this list of considerations for estimates because you should also expect you'll encounter problems that require you to debug Terasology itself.
A lot of the development that's gone in to Terasology over its ten year history has been from people who joined the project with just as much (or little) experience as you have now. In case that gives you any idea what to expect.
Some of those bugs you'll fix yourself. The project will love you for it! Other bugs may fall too far outside your area of expertise for you to fix right now, but you'll still need to take time to document and report the issue. This will help others who run in to the same problem and let the team know they need to make a plan to fix it.
Iterate (Feedback & Review)
Play Testing
Now that you have something running, you can see how it works in the game. Does it work as well as you imagined? Maybe it needs some minor tweaks. Or maybe seeing it in practice teaches you that things don't work that way after all, and you have bigger things to re-think.
Some of that you can figure out by running it yourself, but face it: You're biased. What you see on the screen and how you interact with it is shaped by the ideas in your head that came up with this feature in the first place. This is especially true for subjects like game design and user interface.
In order to really know if it's a good change, you need someone else to play with it. We'll be putting some group play test events on the calendar, but don't hesitate to do smaller impromptu play tests, or get feedback from someone playing single-player and streaming or recording their screen.
Scheduling those test sessions and getting that feedback is another thing that you need to plan for on your timetable. Unless you have a team of beta testers at your beck and call.
Code Review
All your pull requests will be reviewed before they are merged to the project's main development branch. How to give and receive code review is a whole topic unto itself, but here are a few things to keep in mind for planning purposes:
You will have to wait for reviews. The details of who you can expect reviews from and when is something you'll go over with your mentor, but having a review the next day is probably the best case you can hope for. With different schedules, time zones, and priorities, it could be days.
If your PR is small, or you've been getting regular feedback as you go, your pull request might be approved on first review—but don't count on it!
Your reviewer may have clarifying questions or small suggestions. Or they may ask for a change that requires your implementation to take a significantly different approach!
Get feedback early and often. This will reduce the risk of being asked for a big change at the end, just as you thought you were done and ready to move on to the next thing.
Small branches get reviewed faster. A branch that changes a lot of code, or lots of very different code, will likely intimidate potential reviewers. Even if there's someone dedicated to reviewing that area of the project, a small review is something they might be able to do when they have a moment between tasks, and they'll likely put off longer reviews until later when they have more time and energy.
A big part of the process working on long-lived group software projects is learning how to break up tasks in to pieces that aren't too small to bother with and aren't too big to fall out of sync with the rest of the team.
Don't forget to set aside time to do code reviews yourself.
Yes, I know that as a newcomer to the project, you may feel like you're in no position to review anyone else's work in this project you scarcely know anything about. I'm a year in and I still feel that way, though somewhat less often. Going in to the how is outside the scope of this document, but for planning purposes know that there are things you can do to help review and test the work of others.
It's all too easy for an open source project to starve for lack of reviews. Contributing in that way will make the whole project happier and healthier and it's a very valuable skill to develop.
Document
Any user-visible feature needs at least two types of documentation: One for the people who will be using that interface or maintaining that implementation in the future (even if that's just you—future-you needs documentation too), and another for users of the application.
Documentation for players may take the form of in-game help. Please provide in-game documentation in every language you are literate in! Even if that's only one language, plan on using the internationalization API so that others can provide translations of those sections later.
Keep in mind that even a little feature can have a lot of steps:
Design
Sketch out how it looks, what it will do, how people will interact with it. How it relates to the rest of the system.
Discuss this with stakeholders, incorporate feedback.
You will have already done some of this in the act of writing your proposal, but chances are high that between April and June you will have had a chance to refine these ideas and thought of more questions to ask and met more people to talk to about them. That all means some of your time will likely spent re-visiting your designs.
Research
If you haven't worked in this area of the project recently, it will take you some time to become familiar with the relevant interfaces and terminology.
Whenever you switch between different types of features—e.g. terrain generation, user interface, entity behavior, different game modes—you'll be introduced to a new part of the system. Don't forget to account for that transition time if you propose working in multiple areas.
(Have you counted how many classes there are in Terasology? Sure, they're not all public, but how many of them are? How many more are currently in the modules that your project will be working with?)
Media Assets
Adding an new type of object to the world? It may need
- a 3D model (if not a standard block)
- Will it be animated? Does it have joints or other moving parts?
- textures
- sounds
- icons for use in inventory, etc.
If you're not creating an asset, where will it come from? You may be able to take advantage of existing third-party assets, but
⚠ to include any content in Terasology we must have an appropriate license for it. ⚠Is there any conversion necessary between the format it is published in and the format the game can load?
Implementation
Write the classes and methods that implement the logic the feature requires. If you're joining us from a curriculum focused around individual programming exercises, this is the part that likely first came to mind when thinking about how long it will take to write a feature.
Testing
Most code benefits from automated tests to help give you confidence that what you're building is behaving correctly, and things continue to behave correctly as you or others make changes. Terasology has test suites with both unit tests and integration tests. Plan to write tests as you go, not as a separate deliverable at the end.
You may find some things impractical to write automated tests for. For those cases, keep notes in your pull request about the things that testers and reviewers should look for when they run your branch.
Things to confirm after you get an initial proof of concept working:
- Restart the game and load the save.
- Did it save everything it needed to?
- Does it still behave the same way now as it did in the first run when the world was first created?
- Multiplayer.
- Does it show up correctly for all players on the server?
- Any interactions between players?
- Problems when someone disconnects and rejoins?
- Performance. Check for changes in:
- Client FPS or server tick rate.
- RAM usage.
- Network traffic.
Debugging
You've written enough code to have some idea of how long it takes you to get something you've written to work as intended. That's a normal part of implementation and testing.
I bring up debugging in this list of considerations for estimates because you should also expect you'll encounter problems that require you to debug Terasology itself.
A lot of the development that's gone in to Terasology over its ten year history has been from people who joined the project with just as much (or little) experience as you have now. In case that gives you any idea what to expect.
Some of those bugs you'll fix yourself. The project will love you for it! Other bugs may fall too far outside your area of expertise for you to fix right now, but you'll still need to take time to document and report the issue. This will help others who run in to the same problem and let the team know they need to make a plan to fix it.
Iterate (Feedback & Review)
Play Testing
Now that you have something running, you can see how it works in the game. Does it work as well as you imagined? Maybe it needs some minor tweaks. Or maybe seeing it in practice teaches you that things don't work that way after all, and you have bigger things to re-think.
Some of that you can figure out by running it yourself, but face it: You're biased. What you see on the screen and how you interact with it is shaped by the ideas in your head that came up with this feature in the first place. This is especially true for subjects like game design and user interface.
In order to really know if it's a good change, you need someone else to play with it. We'll be putting some group play test events on the calendar, but don't hesitate to do smaller impromptu play tests, or get feedback from someone playing single-player and streaming or recording their screen.
Scheduling those test sessions and getting that feedback is another thing that you need to plan for on your timetable. Unless you have a team of beta testers at your beck and call.
Code Review
All your pull requests will be reviewed before they are merged to the project's main development branch. How to give and receive code review is a whole topic unto itself, but here are a few things to keep in mind for planning purposes:
You will have to wait for reviews. The details of who you can expect reviews from and when is something you'll go over with your mentor, but having a review the next day is probably the best case you can hope for. With different schedules, time zones, and priorities, it could be days.
If your PR is small, or you've been getting regular feedback as you go, your pull request might be approved on first review—but don't count on it!
Your reviewer may have clarifying questions or small suggestions. Or they may ask for a change that requires your implementation to take a significantly different approach!
Get feedback early and often. This will reduce the risk of being asked for a big change at the end, just as you thought you were done and ready to move on to the next thing.
Small branches get reviewed faster. A branch that changes a lot of code, or lots of very different code, will likely intimidate potential reviewers. Even if there's someone dedicated to reviewing that area of the project, a small review is something they might be able to do when they have a moment between tasks, and they'll likely put off longer reviews until later when they have more time and energy.
A big part of the process working on long-lived group software projects is learning how to break up tasks in to pieces that aren't too small to bother with and aren't too big to fall out of sync with the rest of the team.
Don't forget to set aside time to do code reviews yourself.
Yes, I know that as a newcomer to the project, you may feel like you're in no position to review anyone else's work in this project you scarcely know anything about. I'm a year in and I still feel that way, though somewhat less often. Going in to the how is outside the scope of this document, but for planning purposes know that there are things you can do to help review and test the work of others.
It's all too easy for an open source project to starve for lack of reviews. Contributing in that way will make the whole project happier and healthier and it's a very valuable skill to develop.
Document
Any user-visible feature needs at least two types of documentation: One for the people who will be using that interface or maintaining that implementation in the future (even if that's just you—future-you needs documentation too), and another for users of the application.
Documentation for players may take the form of in-game help. Please provide in-game documentation in every language you are literate in! Even if that's only one language, plan on using the internationalization API so that others can provide translations of those sections later.