Contributing

There are many ways you can contribute to this project. Even if it's just a simple Java app, the contributors are not just limited to developers. One of our first contributors is a designer. Apart from developers, we need writers and translators to write, translate and proofread the docs and in-app texts. We also need designers to create awesome and custom app designs. If you are interested, then just keep reading below and let's hope you find something you can contribute to.

Pull requests

Pull requests are fundamental for the project to grow. If you find something of the app you would like to improve and you know how to do it or want to make the first step, then this is the type of contribution for you. You will need to fork the repository first, add your change and pull it back up to the main branch. Every pull request will be reviewed in detail and discussed on Github. So please, after you have submitted a pull request, stay with us as we go through the process of reviewing the request. We know that some people are afraid of submitting pull requests because they are afraid of making mistakes. But remember, nobody is perfect, everyone makes mistakes sometimes. If you submit an incorrect pull request we will not yell at you, we will give you detailed feedback on how to improve it and give you the chance of trying again. Here is a step by step guide to submit a pull request successfully: 1. First of all you will need tools to work with. We highly suggest you download Android Studio and Github Desktop. 2. After you have downloaded your tools, now it's time to download the project you will be working on. You can do this by forking the Repository. 3. Now you should have all the files you need on your computer, you can therefore start to change whatever part of the code you want. Please do note that the branch gh-pages cannot be edited! 4. Open Android Studio and import the whole project, then run the build.gradle file. 5. Now all files should be updated and you should be ready to make your changes. 6. Once you are satisfied with your changes and would like to submit them for review, you can simply use the Github Desktop app to upload the files to the repository you forked earlier. 7. You can repeat the step above multiple times with as many changes as you want. Once you are done, you can finally create a pull request for the main project. 8. If you navigate to the repository you can open a new pull request and submit your code 9. Try to be as detailed as possible when describing your change, also try to include external sources you used as a reference if possible.

This was a very brief tutorial on how to create a pull request, for a more detailed and beginner-friendly tutorial please visit the Github tutorial directly. Note: The pull requests can have the same labels as issues, refer to them in the section below!

Issues

Issues are a very important part of the project. Issues are not just bugs, but also suggestions and improvements. If you find something odd in the app, would like to suggest an improvement, or think there is a security vulnerability, you can just use one of the Issue templates and submit your thoughts. One important thing you need to do before submitting your issue is to take a look at the past open and closed issues to avoid creating a duplicate issue. If you find that your issue has already been submitted but you want to add some more detail to it you can always do that, even if the issue is closed. We normally don't lock conversations and therefore everyone can submit his thoughts and request a more detailed explanation if needed. While exploring issues you might be wondering what some labels mean. We usually use the standard Github labels, we don't have custom ones yet. Here is a shortlist: - Bug: Bugs are errors in the app where the app doesn't behave as it should. When this label is applied it means that the issue is related to some sort of malfunctioning of the app. - Enhancement: Enhancements are essentially improvements and suggestions to the app. When this label is applied it means that the person opening the issue would like to request a change in the issue, the issue might or might not have a pull-request assigned where the person already implemented the new feature he/she requested. - Documentation: This label refers to everything that is not directly related to the app, but has to do with the docs. If you want to contribute to this type of issue, you might find the section about Translations below if you interest. - Duplicate: This label means that the issue already exists. When an issue already exists, the existing issue will be mentioned in the issue discussions section and then closed immediately. - Good first issue: This type of issue is great for new contributors. It is mostly an easy-to-do task and therefore great for new people who would like to be part of the contributors of the project. - Help wanted: This label is generally added to an issue that is harder to fix. We are a small team and we can't do everything, sometimes we struggle a lot and if you see an issue like this and know how to fix it you are very welcome to do so. - Question: Do not confuse this label with the one above! This label means that we don't understand your issue and need more information on how to fix it. When we apply this label we also provide some questions in the issue. If you have answers to those questions you can answer them. - Invalid: If we think that the issue is not related to the SocyMusic project or nobody can clarify the issue it will be flagged as invalid and closed after some time. To avoid this, please try to be as detailed as possible while writing issues and remain open to questions we might have. - Wontfix: This is the only label that immediately blocks any development on the issue. It means that whatever got reported or suggested will not be fixed or coded. This happens very rarely, but it might be the case if it somehow breaks the Concept of the app.

Discussions

Discussions are the best way to communicate on Github. Especially if you are unsure to open an issue about it or not, it's a great place to discuss it. Discussion is also a great place to submit translations or designs. Check out the respective sections below for that. Some categories are locked, which means only administrators or maintainers can create discussions in that category, but people are still able to comment on them. Some categories are completely open, which means everyone can open their discussion in there and comment as they like. And the last type of category is the question and answer one. It's like the completely open one, but the difference is that people will only be able to ask questions and provide answers. There is also the possibility to vote for the best answer. Here is a list of currently existing categories and their purpose: - Announcements: This category is all about telling whoever is reading what has been done. For example, when there is a new release, a discussion for it gets created automatically to allow people to discuss it. It is also used to announce special events or goals that have been reached. - Design: This category is all about your design suggestions. We want to avoid the need for the designers to create issues for their design creations. This also allows us to organize submissions better and for other people to discuss them. Please refer to the section below on how to contribute properly. - General: As the name already suggests, there is no strict rule here. If you think your discussion doesn't fit any of the other categories you are free to submit it here. We mostly use it to communicate with each other about new changes, suggestions, and more. - Ideas: This category is specifically for new suggestions which need approval from the community or further development. The difference between this and creating an issue is that when creating an issue you need to submit as much detail as possible, but in a discussion, you can also just write down your thoughts. - Q&A: Questions and Answer is a special category that should help in solving simple questions which don't require opening an issue. You should only ask questions here and they will be answered with answers that people can vote on. Once the question has been answered, please mark the answer that solves it. - Show and tell: When you made something great you are proud of and would like to share it with the others of the SocyMusic community, this is the place for you. - Translations: If you know any other language than English and would like to submit your translations of the docs or app, this is the place to do it. Please refer to the section below on how to create translation contributions properly.

Note: In the Discussions tab, the same labels as the Issues apply!

Translations

Translations are a very important part of SocyMusic. It helps in making the project available globally. Let's get straight to the point: There are two types of translations, the one in the app and the one in the docs/GitHub repo.

  • App translations: All the texts in the app are in a file called strings.xml. There you will find all the strings you need and you can translate thsóse into whatever language you want. Please do look into the Translations discussion to avoid duplicate translations submissions. You can also suggest changes to existing translations in the discussions

  • Docs/Github translations: Again, before you submit any translation, check if the language you want to translate into already exists or not by looking in the assigned Translations discussion category. As for the Github repository, you can find all the files you need here, just look for .md files and start translating. For the docs, you can find everything in this folder. To make it easier for you you can use this great free online tool to visualize your text in Markdown in real-time. You can also customize it with emojis and custom formatting, but please add those changes separately so that we can add them to the other versions as well.

Design

Now you might be thinking, why does a music player need designers? And the answer is customization. The app is completely open-source, created by the community for the community. Therefore the designs are custom. At the moment if you look at the backgrounds, they were made by one of our designers. If you have any suggestions for a new logo, new backgrounds, new colors, etc, you can just submit your great artwork at the Design discussions. We will carefully look at every submission and add them if possible. If you would like to remain anonymous, you can always mail us the design by email following the Contact section.