Create an Issue

Our vision is to use the AixLib issue tracker as the central platform to communicate about all our work. Therefore, use it to inform everyone about your plans before you write the first line of code. Your goal should be to inform everyone who can help you, join the development to learn together and who may re-use your model in the future. Therefore, please do not use 1-line descriptions such as "Add new building model". Instead, try to briefly answer all the questions from the "Think and plan what you want to do"-section for anyone who reads your description. Use the predefined template for answering the following questions:

• What is your problem?
• Why do you want to solve it?
• How do you want to solve it?

In addition, it is great if you can quickly summarize the results of your search for previous work.

After you created the issue leave a comment for further information. The first comment should contain the newest progress. Therefor, your first comment should be updated regularly.

More useful tips can be found below.

Best practice for Issues

This is largely copied from the GitLab Handbook

1. Always create an issue for things you work on. If it is worth spending time on, it is worth creating an issue for it since that enables other people to learn and help. You can always edit the description or close it when the problem is something different or disappears.
2. If two issues are related, crosslink them (a link from each issue to the other one). Put the link at the top of each issue's description with a short mention of the relationship (Report, etc.). If there are more than 2 issues, use one issue as the central one and crosslink all issues to this one.
3. After a discussion about a feature update the issue body (The very first post describing the issue) with the consensus or final conclusions. This makes it much easier to see the current state of an issue for everyone involved in the implementation and prevents confusion and discussion later on.
4. Submit the smallest item of work that makes sense. When creating an issue describe the smallest fix possible, put suggestions for enhancements in separate issues and link them. If you're new to AixLib and are writing documentation or instructions, submit your first merge request for at most 50 lines.
5. Do not leave issues open for a long time, issues should be actionable and realistic. If you are assigned to an issue but don't have time to work on it, assign it to someone else. If nobody is assigned to an issue and it is not a priority, please ensure the community can help and close it. (For discussion)
6. We try not to assign issues to people but to have people pick issues in a milestone themselves.
7. Assign an issue to yourself as soon as you start to work on it, but not before that time. If you complete part of an issue and need someone else to take the next step, re-assign the issue to that person.
8. When re-assigning an issue, make sure that the issue body contains the latest information. The issue body should be the single source of truth.
9. When working on an issue, ask for feedback from your peers. For example, if you're a designer and you propose a design, ping a fellow designer to review your work. If they approve, you can move it to the next step. If they suggest changes, you get the opportunity to improve your design. This promotes collaboration and advances everyone's skills.
10. If you ask a question to a specific person, always start the comment by mentioning them @member; this will ensure they see it if their notification level is mentioned and other people will understand they don't have to respond.
11. Do not close an issue until it is fully done, which means code has been merged, all issue trackers are updated and any documentation is written and merged.
12. When closing an issue leave a comment explaining why you are closing the issue.
13. If a user suggests an enhancement, try and find an existing issue that addresses their concern, or create a new one. Ask if they'd like to elaborate on their idea in one of these issues.