mxd — Space Mission Design Support Tools

Dependencies needed to build mxd.

• A C++ compiler supporting the C++17 Standard.
• CMake 3.10.0 or greater.
• GLFW 3.2.1 or greater.
• GLEW 2.1.0 or greater.
• GLM version 0.9.9.3 or greater.
• Google Test Framework version 1.8.1 or greater.

Developer Guidelines

mxd is built of components. A component is a triplet (name.hpp, name.cpp, name.t.cpp) with the following characteristics:

• name.hpp declares the interface for the component.
• name.cpp defines the implementation of the component.
• name.t.cpp provides unit tests for the component.

All components live under src in a flat arrangement (no sub-folders). In the future, when we understand mxd better, we may sub-divide src into sub-directories, but not right now.

Some hard rules:

• name.hpp cannot #include any third-party library (only C++ Standard Library and possibly other headers from the mxd library).

• name.cpp will #include "name.hpp" as the first line of source code.

• name.t.cpp will #include "name.hpp" as the first line of source code.

• All tests are written using Google Test Framework and are named after the (Component, Feature) tested. Additionally, they will be stand-alone (will have a int main()). For example:

TEST(Name, FeatureWithinName) {
// ... some assertion.
}

TEST(Name, AnotherFeatureWithinName) {
// ... some assertion.
}

TEST(Name, YetAnotherFeatureWithinName) {
// ... some assertion.
}

int main(int argc, char** argv) {
  ::testing::InitGoogleTest(&argc, argv);
  return RUN_ALL_TESTS();
}

Some guidelines:

• We use UNIX newlines: \n (as opposed to Windows newlines \r\n). Please configure your Git client to clean the newlines before storing the commit (google how to do it).

• Your commit messages should look as follows:

  1. The title of your commit will be 80 characters or less.
  2. The body of your commit will be as long as it needs to be.
  3. The title will always be a single sentence that starts with an imperative verb.
  4. There is no period at the end of the title.

Some good commit messages:

Implement feature 3

Fix issue #112233

Update build configuration
The new configuration is meant to address [...]

Some bad commit messages:

Bad because it does not start with a verb

the method is broken, so I fixed it

Bad because it capitalizes wrong

implement feature 3

Bad because it has a verb, but it is not imperative (should have been Fix the bug)

Fixed the bug.

If we follow these simple guidelines, the logs generated by git look amazing. If we don't, they look horrible. We want them to look amazing and be a description of everything we have done.

Pull Request Guidelines

1. Create a Pull Request (PR) to add modifications and wait until code review before merging (even if you have permission to merge in GitHub).

2. Keep your changes small. Very small. It is way simpler to fix a small PR than it is to reject an entire, large PR because some tiny thing was wrong. We don’t mind if we receive 20 PRs as long as we can check one by one without thinking too much.

3. Add comments to the PRs in the Comment Section (briefly explain what problem you are trying to solve and why did you solve it the way you did). This is for our own amusement; it is to document our collective rationale.

4. Send the first thing that works, or the first placeholder that makes sense, even if it has minimal or no implementation. Don’t wait until everything is perfect (incremental and small changes are a good thing).

5. Add unit tests for mostly everything. If you added a placeholder, add a failing test reminding you to add an implementation. This will allow us to run the tests and find out what we are missing.

6. Talk. If you don’t know how to do something, or are having trouble, open a conversation (Issue Section, with an appropriate label). Chances are that if you have trouble, someone else will also have trouble, and that conversation will help those people in the future. Good software is made by open and frank communication, and is never a competition on who is the smartest.

7. Do the obvious, not necessarily the most elegant or inspired solution. Simple code is good code. Clever code is bad code unless it is also simple. We can always improve on the obvious, but it is difficult to improve or maintain code that someone came up with during a flash of inspiration and then forgot how it happened.

8. Keep comments to a minimum. Write code in a way that it speaks for itself (e.g., good variable names, good function names, good flow, separate steps in separate lines, and so on). This does not mean you should not document your rationale or explain a tricky or non-obvious step; document those profusely.