|
|
The purpose of this knowledge base is to help newcomers settle in our group easily. Please feel free to edit and expand it.
|
|
|
The purpose of this knowledge base is to help newcomers of any experience level settle in our group easily. Please feel free to edit and expand it.
|
|
|
|
|
|
# 1. Setting up
|
|
|
|
|
|
TL;DR:
|
|
|
Only some versions of Python work for this project at this time. 3.8.x is preferred, 3.9.x has no known issues, but **3.10.x should NOT be used** as it is incompatible with some of the dependencies as of writng this.
|
|
|
|
|
|
## Python
|
|
|
|
|
|
### Windows
|
|
|
|
|
|
First of all, the preferred version of Python to use is 3.8.x. You can download it (along with other versions of Python) from [here](https://www.python.org/downloads/).
|
|
|
|
|
|
If you're uncertain about setting up the latest version of 3.8 (as the last 3 versions as of writing this were end-of-life Source Only releases), you can find the last installer versions **[here](https://www.python.org/downloads/release/python-3810/)**. It shouldn't be much of an issue if you use 3.8.10.
|
|
|
|
|
|
If you use the installer version, two things are heavily recommended:
|
|
|
1) Be sure that when the installer offers "Install Now" or "Customize Installation" you tick the box at the bottom that offers to add Python 3.8 to PATH. This isn't strictly neccessary, but it will make running Python from the commandline much more comfortable.
|
|
|
2) If you choose to customize your installation, keep 'pip' ticked. It's a very handy tool that lets you quickly and painlessly install various python packages, including some dependencies of this project like Librosa.
|
|
|
|
|
|
Once you have Python installed, be sure to double check you don't have an incompatible Python version on the system. In Windows, different versions of Python will show up as installed software in the Apps and Features menu of Windows Settings where you can uninstall software. If you have a version of 3.10.x, it will generally supercede your 3.8 installation, even if said 3.8 version was released after the 3.10 version you have installed (yes the versioning is a bit weird with Python).
|
|
|
|
|
|
To double check your active python is correct, it's best to end everything by opening a command prompt (Windows Key + R then type in "cmd" and press OK) and type in "py --version". If the commandline prints out Python x.x.x where x.x.x is the version you just installed, then it's all good!
|
|
|
|
|
|
|
|
|
## Git
|
|
|
|
|
|
### Setting UP
|
|
|
|
|
|
TODO
|
|
|
|
|
|
### Basic terms
|
|
|
|
|
|
There's a couple of basic terms that are absolutely fundamental to using Git, so here's a quick summary:
|
|
|
|
|
|
#### Pull
|
|
|
|
|
|
Essentially, to 'pull' means that you download a local copy of the repository as it exists at that time on the Gitlab servers. If you were actively adjusting one of the online branches on your local copy, Git would attempt to weave the changes together, however this shouldn't be the case here, as it is heavily recommended you start a new branch when working on a part of the project. (See 4. Project Standards)
|
|
|
|
|
|
#### Commit
|
|
|
|
|
|
Committing should not be confused with Pushing. The best way to imagine it, is that each committed version of the project exists backed up as a copy. When you Pull the project, you download all previous commits and load the latest. Because Git keeps track of what the changes were between commits, changes can always be 'Rolled Back' to a previous commit.
|
|
|
|
|
|
Each commit is essentially a checkpoint within the development of the project, which unless the project is corrupted due to some force* will remain idefinietly, as long as at least one copy of the repository exists. When you 'commit', it's essentially a statement that you want to keep that version of the project, either because it's a new, stable version of the project, or — more likely in our case — because you want to Push it to the online repository so others can keep track of your progress, or you're getting ready for the Merge Request.
|
|
|
|
|
|
*- Usually this only happens if something exceptionally outrageous occurs, such as someone putting copyrighted material into the repository, which then needs to be completely deleted. As a side note, please do not include copyrighted materials for this reason. If you want to use external code which might be copyrighted, check for a license, and also preferably communicate with someone from the team.
|
|
|
|
|
|
#### Push
|
|
|
|
|
|
The inverse of Pull. You select a commit within your own personal version of the repository, and update the server with every commit upto and including that one from your local version. Normally, this includes merging of changes within the same branch, but as Git would handle this automatically, we instead prefer performing changes on separate branches for which a Merge Request is neccessary before your changes become final for the main project. (See 4. Project Standards)
|
|
|
|
|
|
#### Branches and Merging
|
|
|
|
|
|
There could be a cute way to describe what they are by drawing a parallel to the expansion of the hit Westwood classic Red Alert 2, and its meddling with timelines and timeline mergers, but that would get confusing so to put it in easier terms:
|
|
|
|
|
|
Essentially, a branch is a line of commits. When you make a branch, you're actually making a copy of a pre-existing branch, while marking "this was actually that original branch up until this point" at the start. Then, you keep working on that branch like normal.
|
|
|
|
|
|
This is fundamentally not too different from Pulling the branch, but it removes your ability to Push to the same branch, or to Pull changes from the original branch. (Technically, if two different people Pull the same branch, start making changes to it on their own computers, creating new commits without creating a branch first, that creates imaginary branches as well. However, these are considered both to still be the original branch, thus they can be Pushed, and their changes get merged automatically by Git without manual review.)
|
|
|
|
|
|
Branches are thus useful to let you make changes, and even push them to the repository, without endangering the original branch's consistency. Because branches need to be manually merged with their original branch via a Merge Request, this means a manual review by others is possible, minimizing the chance of errors or incomaptibilities propping up and compromising the main branch, which would require Rolling Back which might ruin a great deal of effort or come with a host of headaches.
|
|
|
|
|
|
#### Roll Back/Revert
|
|
|
|
|
|
Very simply as summarized before, the act of selecting a commit that is not the latest commit and restoring its state. The commits created beyond this point are not technically erased, however, they are functionally archived, meaning any additions or fixes contained therein need to be recreated.
|
|
|
|
|
|
Rolling back is generally avoided where possible because of this.
|
|
|
|
|
|
## Recommended Envoriments
|
|
|
|
|
|
This isn't so much a guide, just possible software to use while working on the project to make your work easier, so you don't need to work using exclusively command prompt and Notepad++ unless you really want to.
|
|
|
|
|
|
Feel free to add alternatives.
|
|
|
|
|
|
### [Windows Studio Community](https://visualstudio.microsoft.com/vs/community/)
|
|
|
|
|
|
One of the standards, once installed, simply open it, press 'File'>'Clone Repository' and add in the online address of the project. When it asks for credentials, simply use your Gitlab login, and it will automatically pull the latest version of the repository.
|
|
|
|
|
|
Most Git operations can be performed with a few clicks using the Git tab at the top, most notably "Commit", "Push" and "New Local Branch", which you should use at the start of making adjustments (See 4. Project Standards).
|
|
|
|
|
|
If you want to pull the latest version of the master inside WSC for reference while working on a branch, you first must 'Manage Branches' and check out the master branch. Then, must manage and check out your own branch to continue working on it. Keep in mind that even if you update the master branch on your local copy, changes made to it since you created your own branch will not apply until merging. And merging should only be done once the branch was pushed to the main repository and the request was reviewed.
|
|
|
|
|
|
# 1. Python
|
|
|
|
|
|
The recommended version of Python is 3.8.x, as it is the latest stable version available to the most popular Linux distribution.
|
|
|
3.9.x may be viable, however be warned that as of writing this, **3.10.x should NOT be used**, as some dependencies of the project simply aren't compatible with 3.10.x.
|
|
|
|
|
|
# 2. Music Information Retrieval
|
|
|
|
... | ... | @@ -18,4 +93,45 @@ Other important topics: |
|
|
- Music and rhythm notation
|
|
|
- Interval and chord inversions
|
|
|
|
|
|
For questions ask @wp5ly5. |
|
|
\ No newline at end of file |
|
|
For questions ask @wp5ly5.
|
|
|
|
|
|
# 4. Project Standards
|
|
|
|
|
|
This section is a little verbose, as the lab includes and can include people of any experience level. A bullet point 'TL;DR' version should be included at the end of every segment for those that are familiar with such things.
|
|
|
|
|
|
## Commits, Branches and Merges
|
|
|
|
|
|
As a general rule, do not commit to the master branch of the project when you're working. Instead, after pulling the master branch (or another branch if you find yourself making adjustments to a different branch for whatever reason), create a new branch for yourself.
|
|
|
|
|
|
As you are working, commit your status to your local repository on your computer, and feel free to push this new branch to the repository as well. In fact, it is strongly encouraged. Even if your code is not working correctly yet, is incomplete, or parts of it are either temporary patchwork or 'sphagetti code', it doesn't hurt to let others see where you're at. Feel free to comment "temporary" or something to that effect in parts of your code you intend to replace.
|
|
|
|
|
|
Once you feel your branch is complete, and what you wanted to add to the master branch is implemented, make sure the latest branch is pushed to main server and check it's here on the GitLab server.
|
|
|
If it's here, navigate to the Merge Requests tab on the left, and you should see at least one button labelled "New merge request" in the upper right.
|
|
|
|
|
|
Clicking that, you'll be taken to a screen, where you can select your branch as a source, and target the branch from which you originally split it for merging. (This will usually be the master branch, but if you were making adjustments to another branch, be sure to select that, unless it was already merged into something else, in which case select that and so on.)
|
|
|
|
|
|
Finally, after the merge request was created, the whole team will see a notification about it. Some of us will go over it, check it for any issues and note them if there are any, or otherwise give our approval. Once it's been checked and no issues were found, the merge request will be approved, and your additions will be added to the original branch!
|
|
|
|
|
|
See Peace of Mind section in case you're worried about merging.
|
|
|
|
|
|
[:airplane: Would you like to know more?](https://docs.gitlab.com/ee/user/project/merge_requests/)
|
|
|
|
|
|
TL;DR:
|
|
|
- Don't work on master branch, pull it, then create your own and tweak that.
|
|
|
- Commit and push your work often so others can see and think ahead based on your work.
|
|
|
- Submit a merge request when you feel you're ready, and wait for it to be checked and approved.
|
|
|
|
|
|
|
|
|
# 5. Notes for Peace of Mind
|
|
|
|
|
|
This section is generally for people who feel a little nervous, as this might be their first project, and have little experience with either group projects in general, or just some parts of the process, like Git operations.
|
|
|
|
|
|
## 'What if my branch won't play nice with the stuff others are working on?'
|
|
|
|
|
|
It is technically possible that issues will arise while trying to merge branches, primarily if both branches have changes to the same parts of the same file. For example, both branches edited the same function, renamed the same variable, etc.
|
|
|
|
|
|
To mitigate these issues, is part of why it's highly recommended that as you work, you keep pushing your changes on your own branch to the repository, so everyone who's working on the same code can see if you're making any changes, and either adapt their own work, or get in contact to work out some compromise.
|
|
|
|
|
|
If an issue does arise, the team will need to do some manual work to make the two branches compatible, but this is simply par for the course in software engineering, so don't worry about it.
|
|
|
|
|
|
That being said, this is all only if an issue arises that Git can't handle on its own. As noted, issues will only really prop up if the same part of the same file is touched. Git's pretty good at automating certain kinds of merges. If you simply add new functions or variables to a file, or create branch new files, Git will be able to apply these changes during a merger without issue. Most of this is automated, and problems can be solved. |
|
|
\ No newline at end of file |