Contributors Guide: Welcome!

Hi! We’re glad you’re interested in contributing to Crosswords.

We welcome all sorts of contributions: code, art, documentation, testing, feedback etc. Here are some guidelines to make your experience smooth.

For those needing help navigating the codebase, a codebase overview is available.

Have fun!

Conduct

This project follows the GNOME Code of Conduct. It ensures that everyone in the Crossword’s community is treated with respect and has a good time. This is taken seriously, and strictly enforced.

AI Code

We allow careful AI use in this project, but strongly discourage it for new contributors. All AI-procuced code must be hand-reviewed before submission (and possibly fixed or rewritten). In addition, any use of AI must be disclosed in the MR overview.

A note for potential GSoC and Outreachy students

We participate in GSoC and Outreachy regularly.

The initial phase of these programs encourage students to make some contributions to to get familiar with the project and codebase. These contributions are also really useful for the maintainers to get a good grasp of what the participants are capable of. It is used to help assess their skills, instincts, communication abilities, and talents as an engineer. AI-based submissions show none of that.

AI Code Contributions are strictly prohibited during this phase.

The main point of us this phase is to build trust. Trying to sneak in AI code contributions is a breach of this trust, and will lead to not being picked for the program.

AI Exception

For non-native English speakers, light use of AI to clean-up or understand language is encouraged.

Docs

Any decent-sized changes should have a design doc before writing code. We will reject any big, non-trivial CLs without an approved design.

This is imporant for both parties! It will prevent a lot of time spent on a feature that will need to be reimplemented, and it prevents

It’s always easier to refactor words than code.

Git Suggestions

  • Please, please try to make MRs do one thing. An MR should not add a feature, then fix unrelated things as a driveby. Please submit fixes as additional MRs — we’d much rather have three unrelated MRs than try to untangle one larger one.

  • Commit messages should be consise and to the point. Explain the why, not the what.

  • Do more, smaller commits rather then one large one

    • It’s easier to review and I can see your path developing the code

    • It can be reviewed more thoroughly

    • It’s less likely to be buggy..

    • ..and it’s easier to track down bugs with git bisect

    • There’s less waste if rejected

  • Keep intermediate commits compiling, if possible

  • Do not squash commits as part of a merge