-
Notifications
You must be signed in to change notification settings - Fork 3
Workshop BEK March 2014 Monday
Present: Trond, Pascal, Adrian, Tim, Théo, Nathan, Henrique
At 14:00, Henrique gave a presentation on how to create a successful Git workflow. To illustrate his points, he showed a diagram from a blog post by Vincent Driessen. Under this model, the dev branch becomes the primary place to make changes and the master branch is reserved for releases. Although we agreed to adopt this workflow model at the Albi 2013 workshop, there have been times since when developers are still committing to master.
We recognized the need for a blog post that would explain the preferred workflow when acting as a Jamoma contributor. This could also be captured in the contributing.md file of the umbrella Jamoma repository.
Tim also suggested that automatically closing issues via commits should be avoided. This is primarily because the issue will only be closed once the commit is merged to master (something we will be doing less often under this workflow), and additionally we risk opening and closing issues multiple times.
Jamoma is currently structured with an umbrella repository that contains both Core and its various implementations. Henrique explained that a submodule inside an “umbrella” repository is treated by Git as a file, not a folder structure or full repository. The content of this file is simply a pointer to the commit hash. When you pull from a branch on the umbrella, you will end up with “detached HEADs” and need to sync your submoldules again to a branch.
This lead to a discussion of the intent for version numbering. We discussed having different kinds of releases - for Max, Core, plugin implementations, etc. - and how to best do version numbering on the Jamoma umbrella repository. What should a number mean? Should the version numbers stay in sync between Core and the Max implementation (and other implementations)? How do we handle implementations that may be stale? Currently there are several implementations (VST, AudioUnits, pd) that have not been updated in over a year, but they are receiving new version numbers under our current workflow.
As an aside, Henrique also recommended two tools that he finds very useful for manage his Git workflow: Oh My ZSH and gitxL.
We moved into an extended discussion about how to organize our submodules with the umbrella repository. Possible options:
-
Core is a submodule of each and every implementation:
- Disadvantages:
- Doxygen will need to be set up again and again for each implementation if it is to cover implementation as well as Core.
- Implementations would need to responsible for building Core themselves.
- This could be a time consuming reconfiguration that would distract us from getting 0.6 out of beta
- Advantages:
- Stale implementations are more likely remain usable since they simply point to a specific commit on the Core repository.
- Disadvantages:
-
Core and Implementations co-exist at the same level within the folder structure (i.e., the current configuration).
- Disadvantages:
- This has the potential to be more difficult for new users and developers if they are only interested in a single implementation.
- Advantages:
- It makes it possible to maintain Doxygen documentation that spans the Core and Implementations.
- Disadvantages:
Conclusion: Reorganisation and any decision concerning reorganisations are postponed, so as not to further delay the release of 0.6. We will continue today’s practice, but change how releases are being tagged, in order to cater for parallel implementations:
- We only tag the top Jamoma repository
- Tags are to be labeled “Max/0.6.0.a29”. This way we can also have “Ruby/0.1.b23” etc.
- Existing tags should be renamed accordingly
At about 15:15, Nathan presented on the Unit testing. Most of this information is contained within his recent blog post, but he was able to step through and show the individual elements that went into build and test. He was also able to talk about how individual libraries are configured to take advantage of the system and how one would configure new libraries when they are added the Core.
Tim explained that the build and test would not be helpful in the event of a crash in the test. In this case, he showed the following steps to debug using schemes in Xcode:
- Start by creating a new target with the External Build System option
- For this new target, change the Info > Arguments from the default $(ACTION) to notest
- Build the library
- Next create a new scheme for the project and edit it
- For this new scheme's settings, change the Run > Info > Executable from the default of None to choose either the compiled test32 or test64 which should be located in the project's build folder
This should allow you to run the test, apply breakpoints and use the other debugging features in Xcode. For now, we should make sure that this setup is not committed to the repository, because it would defeat the purpose of integrating the build and test. We want these to remain linked so that we discover bugs as soon as possible.
After a short break, we re-started at 16:20 with a presentation by Tim about his work for Cycling74 to develop an integration testing solution for Max. Using a package distributed to those in attendance, he demonstrated the automated testing suite they hope to soon make the preferred method for reporting bugs. The oscar extension provides the basis for several externals that show up in Max, including the test.assert object.
Although this work is currently in beta, it is likely to become the preferred way to report bugs within Max. Tim described the advantages of this system, including the ability of the patch to document the user's expectations for an object. Additionally, the results of these integration tests are recorded into an SQL database, which makes it possible to query the results in unique ways.
Conclusion: We should begin the process of adapting our current integration tests to his new method because of its support by Cycling74.
At 17:00, Nathan provided an review of Doxygen and the comments necessary to generate basic documentation via this utility. Using the TTSampleMartix and TTBuffer as models, he pointed out seven key tags necessary for consistent Doxygen headers across Jamoms:
* @file - identifies the file as a module that Doxygen should process
* @ingroup - contains a tag representing the library or extension
* @brief - single sentence typically starting by the module name
* @details - longer description that may be several sentences
* @seealso - a list of related modules that you wish to link to
* @authors - persons who have made significant conrtibutions to the module
* @copyright - a failure consistent BSD licences description
Tim pointed out that these comments now generate hints inside of Xcode 5 because of new integration, which makes them even more useful while coding. For this reason, developers should be should to add Doxygen comments when creating new classes or making extensive reviews of existing classes. We agreed that taking time to add Doxygen comments to classes is a worthwhile activity and that we should either add them while working or create a ticket to record the need in a specific file.
Discussion was concluded at 17:30.
More thought went into the issue of making Core a submodule on the various implementations. Théo remembered an issue he regularly experiences with iScore and Tim explained that it is caused by library being fixed when you complie with Xcode. Our current solution is to have Core distinguish between the various Implementations in its build scripts, which it shouldn’t need to do. With the proposed change to a Core-as-submodule configuration, this would be less of an issue. It would be the responsibility of the Implementation to compile the Core library from the specified commit.