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. Submit for Review — Open a Pull Request (PR) for all changes. Always await code review before merging, even if you have merge permissions.

2. Keep it Small — Small PRs are easier to review and fix. It's better to send 20 small PRs than a single large one likely to be rejected for minor issues.

3. Provide Context — Add a brief explanation in the PR comments: the problem you're solving and why you chose your approach. This documents our collective reasoning.

4. Iterate Incrementally — Submit the first working version or a sensible placeholder. Don’t aim for perfection—small, iterative changes are ideal.

5. Test Everything — Include unit tests. For placeholders, add failing tests as reminders for implementation. Tests highlight gaps and ensure coverage.

6. Communicate — When stuck or unsure, start a discussion (via Issues, with appropriate labels). Collaboration solves problems faster and helps others facing similar challenges.

7. Favor Simplicity — Prioritize obvious, straightforward solutions over clever or overly elegant ones. Simple code is easier to improve and maintain.

8. Minimal Comments — Write self-explanatory code with clear names and logical flow. Document non-obvious logic and rationale thoroughly, but avoid over-commenting.