# 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](https://jrb.pages.gitlab.gnome.org/crosswords/devel-docs/codebase/index.html)
is available.

Have fun!

## Conduct

This project follows the [GNOME Code of
Conduct](https://conduct.gnome.org/). 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](design-docs.md)
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
