Contributing to scri.be

Thank you for your interest in contributing!

Please take a moment to review this document in order to make the contribution process easy and effective for everyone involved.

Following these guidelines helps to communicate that you respect the time of the developers managing and developing this open-source project. In return, and in accordance with this project's code of conduct, other contributors will reciprocate that respect in addressing your issue or assessing changes and features.

If you have questions or would like to communicate with the team, please join us in our public Matrix chat rooms. We'd be happy to hear from you!

Contents

• First steps as a contributor
• Mentorship and Growth
• Tech stack
• Learning the tech stack
• Development environment
• Style guide
• Linting
• Testing
• Issues and projects
• Bug reports
• Feature requests
• Pull requests
• Website Localization
• Documentation
• Accessibility
• Internationalization
• Design

_{Back to top.}

First steps as a contributor

Thank you for your interest in contributing to Scribe's website scri.be! We look forward to welcoming you to the community and working with you to build an tools for language learners to communicate effectively :) The following are some suggested steps for people interested in joining our community:

• Please join the public Matrix chat to connect with the community
  • Matrix is a network for secure, decentralized communication
  • Scribe would suggest that you use the Element client
  • The General channel would be a great place to start!
  • Feel free to introduce yourself and tell us what your interests are if you're comfortable :)
• Read through this contributing guide and the style guide for all the information you need to contribute
• Look into issues marked good first issue and the Projects board to get a better understanding of what you can work on
• Check out our public designs on Figma to understand Scribes's goals and direction
• Consider joining our bi-weekly developer sync!

_{Back to top.}

Mentorship and Growth

Onboarding and mentoring new members is vital to a healthy open-source community.

We need contributors who are onboarded to gain new skills and take on greater roles by triaging issues, reviewing contributions, and maintaining the project. We also need them to help new contributors to grow as well. Please let us know if you have goals to develop as an open-source contributor and we'll work with you to achieve them.

We also have expectations about the behavior of those who want to grow with us. Mentorship is earned, not given.

To be blunt, those who are mainly sending AI generated contributions are not demonstrating an interest in growing their skills and are not helping to develop the project. This is not to say that all uses of AI for contributions are bad, but AI should be a tool, not the contributor itself.

Continued constructive contributions, new open issues, and clear communication helps the project. We would be happy to help community members who can make these contributions to expand their skills and take on further responsibilities.

If you like the sound of this, then we look forward to working with you!

_{Back to top.}

Learning the Tech Stack

The following are the current and planned technologies for scri.be:

Frontend

• Nuxt.js • Vue.js • TypeScript • Tailwind CSS • Headless UI

Deployment

• Docker • Netlify • Vitest

Localization

• Nuxt I18n

Analytics

• Plausible

_{Back to top.}

Learning the tech stack

Scribe is very open to contributions from people in the early stages of their coding journey! The following is a select list of documentation pages to help you understand the technologies we use.

_{Back to top.}

Development environment

1. First and foremost, please see the suggested IDE extensions in the dropdown below to make sure that your editor is set up properly.

2. To setup your development environment, first install Docker and Docker Compose.

3. Fork the scri.be repo, clone your fork, and configure the remotes:

# Clone your fork of the repo into the current directory (including submodules).
git clone --recurse-submodules https://github.com/<your-username>/scri.be.git
# Navigate to the newly cloned directory.
cd scri.be
# Assign the original repo to a remote called "upstream".
git remote add upstream https://github.com/scribe-org/scri.be.git

• Now, if you run git remote -v you should see two remote repositories named:
  • origin (forked repository)
  • upstream (scri.be repository)

4. Create a virtual environment for i18n-check (Python >=3.12), activate it and install dependencies:

   Note

   First, install uv if you don't already have it by following the official installation guide.

   uv sync --all-groups  # create .venv and install all dependencies from uv.lock
   
   # Unix or macOS:
   source .venv/bin/activate
   
   # Windows:
   .venv\Scripts\activate.bat  # .venv\Scripts\activate.ps1 (PowerShell)
   

uv lock  # refresh uv.lock for reproducible installs

5. Start your docker images with the following:

   # --build only necessary with new dependencies.
   docker compose --env-file .env.dev up --build
   
   # And to stop the containers when you're done working:
   docker compose --env-file .env.dev down
   

6. You can visit http://localhost:3000/ to see the development frontend once the container is up and running.

7. Install prek to ensure that each of your commits is properly checked against our linter and formatters:

   # In the project root:
   prek install
   
    # Then test the pre-commit hooks to see how it works:
    prek run --all-files
   

git commit --no-verify -m "COMMIT_MESSAGE"

You're now ready to work on scri.be!

_{Back to top.}

Style guide

Please see the scri.be style guide for details about how to follow the code style for the project. We made these guidelines to assure that we as a community write clean, cohesive code that's easy to write and review. Suggestions for the style guide are welcome.

_{Back to top.}

Linting

For the frontend eslint, eslint-vue and vue-a11y are added via the dependencies to provide linting support.

_{Back to top.}

Testing

Frontend

Static Testing

Please check the formatting of your code using Prettier and run the static type check with eslint before pull requests with the following command:

# Within ./frontend:
yarn format
yarn lint

You can further run the following commands for TypeScript type checks on the frontend:

# Within ./frontend:
yarn run postinstall
yarn typecheck

Automated Testing

We use Vitest for component and unit testing. You can run them with the following command:

# Within ./frontend:
yarn test

_{Back to top.}

Issues and projects

The issue tracker for scri.be is the preferred channel for bug reports, features requests and submitting pull requests. Scribe also organizes related issues into projects.

Be sure to check the -next release- and -priority- labels in the issues for those that are most important, as well as those marked good first issue that are tailored for first-time contributors.

_{Back to top.}

Bug reports

A bug is a demonstrable problem that is caused by the code in the repository. Good bug reports are extremely helpful - thank you!

Guidelines for bug reports:

1. Use the GitHub issue search to check if the issue has already been reported.

2. Check if the issue has been fixed by trying to reproduce it using the latest main or development branch in the repository.

3. Isolate the problem to make sure that the code in the repository is definitely responsible for the issue.

Great Bug Reports tend to have:

• A quick summary
• Steps to reproduce
• What you expected would happen
• What actually happens
• Notes (why this might be happening, things tried that didn't work, etc)

To make the above steps easier, the Scribe team asks that contributors report bugs using the bug report template, with these issues further being marked with the Bug type.

Again, thank you for your time in reporting issues!

_{Back to top.}

Feature requests

Feature requests are more than welcome! Please take a moment to find out whether your idea fits with the scope and aims of the project. When making a suggestion, provide as much detail and context as possible, and further make clear the degree to which you would like to contribute in its development. Feature requests are marked with the Feature type, and can be made using the feature request template.

_{Back to top.}

Pull requests

Good pull requests - patches, improvements and new features - are the foundation of our community making scri.be. They should remain focused in scope and avoid containing unrelated commits. Note that all contributions to this project will be made under the specified license and should follow the code style standards (contact us if unsure).

Please ask first before embarking on any significant pull request (implementing features, refactoring code, etc), otherwise you risk spending a lot of time working on something that the developers might not want to merge into the project. With that being said, major additions are very appreciated!

When making a contribution, adhering to the GitHub flow process is the best way to get your work merged:

1. If you cloned a while ago, get the latest changes from upstream:

   git checkout <dev-branch>
   git pull upstream <dev-branch>
   

2. Create a new topic branch (off the main project development branch) to contain your feature, change, or fix:

   git checkout -b <topic-branch-name>
   

3. nstall prek to ensure that each of your commits is properly checked against our linter and formatters:

   # In the project root:
   prek install
   
    # Then test the pre-commit hooks to see how it works:
    prek run --all-files
   

git commit --no-verify -m "COMMIT_MESSAGE"

4. Commit your changes in logical chunks, and please try to adhere to Conventional Commits.

5. Locally merge (or rebase) the upstream development branch into your topic branch:

   git pull --rebase upstream <dev-branch>
   

6. Push your topic branch up to your fork:

   git push origin <topic-branch-name>
   

7. Open a Pull Request with a clear title and description.

Thank you in advance for your contributions!

_{Back to top.}

Website Localization

Being a community that focusses on language learning, localization plays a big part in what Scribe will eventually be. Those interested are more than welcome to join the team at scribe-org/Scribe-i18n where we work on localizing all Scribe applications via Weblate.

Please run the update_i18n_keys.sh script to load in the most recent version of the Scribe-i18n app texts into scri.be.

_{Back to top.}

Documentation

Documentation is an invaluable way to contribute to coding projects as it allows others to more easily understand the project structure and contribute. Issues related to documentation are marked with the documentation label.

_{Back to top.}

Accessibility

Thank you for your interest in improving scri.be's accessibility. We want our platform to not only be usable for all people, but also to provide a welcoming environment within the development community for all. This section lists a few points to account for when checking accessibility constraints during development:

Transitions

Users who have motion sickness have the ability to disable transitions and animations on their devices. We use the external dependency reduced-motion to disable transitions and animations in this case.

Tab focusing

Tab focusing sadly doesn't work out of the box for many browsers. Chrome works great, but the following changes are needed for browsers to function properly with tabs. We'll test scrib.be against browsers with these settings with the assumption that people who need tab for more control of the interface will be able to activate them.

Firefox

• Go to about:config
• Search for accessibility.tabfocus and check that it's set to type Boolean with value true
• Remove it and select Number instead
• Click on the add button and then enter the value 7

Safari

• Go to Keyboard in System Preferences for your computer (assuming it's a Mac)
• Select Use keyboard navigation to move focus between controls on Mac OS Catalina or All controls on earlier Mac OS versions
• In Safari go to Settings
• Go to the Advanced tab
• Select Press Tab to highlight each item on a webpage

Once the above steps are finished you should be able to use tab to navigate web pages :)

_{Back to top.}

Internationalization

scri.be uses i18n-check to validate our internationalization key-value pairs. The basic commands to check the i18n keys and values are:

# Note: You need to have installed the requirements-dev.txt file in your virtual environment.
i18n-check -a  # run all checks
i18n-check -ki  # run key identifiers check
i18n-check -ik  # run invalid keys check
i18n-check -uk  # run unused keys check
i18n-check -nsk  # run non-source keys check
i18n-check -rk  # run repeat keys check
i18n-check -rv  # run repeat values check
i18n-check -nk  # run nested keys check

You can also run individual checks. Please see the documentation for i18n-check to learn more.

If you do need to edit the directories and files skipped by certain checks, then these edits can be made in the .i18n-check.yaml file. If you're having issues using i18n-check, please feel free to contact the team for support!

_{Back to top.}

Design

Designs for Scribe are done in the public design file in Figma. Those interested in helping with Scribe's design are also welcome to share their ideas using the design improvement template that makes an issue marked with the design label.

All branding elements such as logos, icons, colors and fonts should follow those that are set out in scribe-org/Organization. As the project is fully open source, these elements are also open for discussion. Efforts in making Scribe products professional with a distinct and cohesive identity are much appreciated!

_{Back to top.}