Welcome to the Seedlingo community, and thank you for your efforts to make Seedlingo better! We appreciate your contribution.
- Code of conduct
- Get familiar
- How can I contribute?
- Report bugs
- Suggest enhancements
- Improve documentation
- Implement a fix or feature
- Develop content
- Documentation guidelines
- Coding guidelines
- License
Please help us keep the Seedlingo community open and positive. Participate in the spirit of the Seedlingo Code of Conduct and the GitHub Community Guidelines.
- Try out a live version of Seedlingo at liaizhongzi.com
- Engage the community and ask questions in Seedlingo discussions. Please stop by and say hi.
- Explore the project documentation at Seedlingo - Get started.
- Inspect the nuts and bolts of Seedling by cloning the repository. See the README-section on Development setup for details on how to run Seedlingo in your development environment.
We really appreciate your eagerness to contribute. We would love to have you:
Do not submit an issue to ask for help, rather:
- Use Seedlingo discussions to search for and/or ask for help.
- Search open and closed issues to see if the problem has already been reported. Please add a comment to the existing issue instead of opening a new one.
- If the bug is a security vulnerability, please refer to our security policy.
- If you found a mistake in the documentation, file a documentation requests instead.
Bugs are tracked as GitHub issues.
Create a new issue and select the bug report template.
-
Give the bug report a short title that describes clearly the path to restore correct functionality.
fix: Prevent crash when navigating home
-
Provide a short description of the issue you experience.
-
Describe the exact steps which reproduce the problem in as many details as possible, from starting the app with which browser on what system, through how you ended up with the unmet expectation.
-
Describe the behaviour you observed after following the steps and point out what exactly is the problem with that behaviour.
-
Explain which behaviour you expected to see instead, and why.
-
Feel free to include screenshots and animated GIFs which show you following the described steps and clearly demonstrate the problem. You can use LICEcap to record GIFs on macOS and Windows, and Silentcast or Byzanz on Linux.
-
List environmental factors, like device and browser.
You can submit both feature requests and documentation requests.
- Check the discussions about ideas. Feel free to suggest rough ideas in the discussions, allowing the community to participate in refining them from an early stage.
- Search open and closed issues to see if the enhancement has already been suggested. Please add a comment to the existing issue instead of opening a new one.
Enhancement suggestions are tracked as GitHub issues.
Create a new issue and select the feature request template.
-
Give the feature request a short and descriptive title using present tense, clearly identifying the expected improved situation this change will bring (preferably to the end user).
feat: 马丽 sees feedback to incorrect answer
-
Describe the behaviour you expect to see and how it differs from current behaviour.
-
Provide a step-by-step description of the suggested enhancement in as many details as possible.
-
Explain why this enhancement would be useful to most users.
-
Add a breakdown of suggested implementation actions.
-
Describe alternative solutions, and why they are not suggested.
-
Feel free to include screenshots and animated GIFs which help you demonstrate the steps or point out the part the suggestion is related to. You can use LICEcap to record GIFs on macOS and Windows, and Silentcast or Byzanz on Linux.
-
Consider using prototyping services like Marvel to demonstrate the suggested functionality.
- Check the discussions about documentation and add your thoughts on the current and desired state of the Seedlingo documentation efforts.
- Check open and closed issues for already suggested documentation fixes or improvements. Please add a comment to the existing issue instead of opening a new one.
Enhancement suggestions are tracked as GitHub issues.
Create a new issue and select the documentation request template.
-
Give the documentation request a short and descriptive title using the imperative mood, clearly identifying the improvement to the documentation that this change will bring.
docs: Add content spec section
-
Describe the desired benefit to users and how to improve the documentation to get there. Don't chew over too much. For example, processing all of the documentation in a certain way should be broken down into sub-tasks in separate issues. They can still be submitted together in one pull request.
-
Add more explanation on the rationale behind this change and explain why this enhancement would be useful to most users.
-
Provide a break down of the suggested enhancement in as many details as possible.
Please submit a documentation requests if no existing issues cover your intended contribution.
-
Familiarize yourself with Seedlingo's LICENSE. By contributing to the Seedlingo project, you agree to license your contribution under these terms, and affirm that you have the right to do so.
-
Pick a good first issue or pick one from the prioritized queue on the Documentation project board, then assign it to yourself or post a comment that you are working on it.
-
If you are not yet a Seedlingo collaborator:
- Fork the Seedlingo repository, then proceed to work on your own fork.
-
Create a new branch off of
main
with a short descriptive name starting withdocs/
, likedocs/add-get-started
:git checkout -b docs/add-get-started main
-
Find the documentation in the
docs/
folder and add your improvements according to the issue you picked. -
Follow our documentation guidelines.
-
Commit your changes using a descriptive commit message that follows our git commit message guidelines:
git config --local commit.template .gitmessage # Add commit template once git add --patch # Add files to staging area git commit # Trigger commit message editor with .gitmessage template
-
Push your branch to GitHub:
git push origin docs/add-get-started
-
Create a pull request describing the aim and scope of the added and/or amended documentation according to the pull request template.
-
Answer comments on the pull request and await review and approval.
-
Make changes if requested, and commit them to your branch.
-
Rebase your branch on top of later commits to
main
and force push to your GitHub fork, which will update your pull request:git remote -v # Ensure `upstream` points to `nodepa/seedlingo.git` git remote add upstream [email protected]:nodepa/seedlingo.git git pull --ff upstream main # update main branch to latest upstream version git rebase main -i # rebase onto updated main git push -f # push rebased branch to overwrite remote
-
Get notified when approved and merged.
-
After your pull request is merged, you may want to clean up your fork:
git pull --ff upstream main # update main to latest upstream version git checkout main -f # check out main branch git push origin --delete docs/add-get-started # delete remote branch git branch -D docs/add-get-started # delete local branch
-
Celebrate your successful contribution! 🥳🎉
-
Familiarize yourself with Seedlingo's LICENSE. By contributing to the Seedlingo project, you agree to license your contribution under these terms, and affirm that you have the right to do so.
-
Pick a good first issue or pick one from the prioritized queue on the Development and operations project board, then assign it to yourself or post a comment that you are working on it.
-
If you are not yet a Seedlingo collaborator:
- Fork the Seedlingo repository, then proceed to work on your own fork.
-
Set up your local development environment as described in the README.
-
Create a new branch off of
main
with a short descriptive name starting with<type>/
from our git commit message guidelines, likefix/restore-audio
,feat/mahjong-exercise-type
orrefactor/improve-readability
:git checkout -b fix/restore-audio main
-
Start implementing the issue you picked.
-
Write tests, preferably before you write any code.
- unit tests
- Name the test file the same as your code file,
with an added
.test.ts
extension, and place it in the same folder. - A
fix
MUST have a unit test that DOES NOT pass when thefix
is NOT applied, but PASSES when thefix
IS applied, to reduce the chance of the bug reoccurring (i.e. regression). - Add or amend unit tests to cover added code (100% code coverage is NOT required, but critical paths MUST be covered).
- Treat
describe
as a noun or situation. - Treat
it
as a statement about state or how an operation changes state.
- Name the test file the same as your code file,
with an added
- end-to-end tests/feature tests/integration tests/acceptance tests
- Name the test file by a descriptive name for the feature
and put it in
tests/e2e/specs/
or a subfolder. - Add or amend tests for the user's "happy-path" through a feature.
- Do NOT try to cover every possible fail state or edge case. Fail states tested here should only be ones where the user needs guidance to follow the correct path through the feature. Extensive edge case testing and system failure state testing should be tested in unit tests (see above). End-to-end tests are primarily to verify that units work well with other units, but can also simulate a real user accepting or rejecting adherence to development requirements.
- Name the test file by a descriptive name for the feature
and put it in
- unit tests
-
Follow our coding guidelines.
-
Commit your changes using a descriptive commit message that follows our commit message conventions:
git config --local commit.template .gitmessage # Add commit template once git add --patch # Add files to staging area git commit # Trigger commit message editor with .gitmessage template
-
Push your branch to GitHub:
git push origin fix/restore-audio
-
Create a pull request describing the aim and scope of the added and/or amended code according to the pull request template.
-
Answer comments on the pull request and await review and approval.
-
Make changes if requested, and commit them to your branch.
-
Rebase your branch on top of later commits to
main
and force push to your GitHub fork, which will update your pull request:git remote -v # Ensure `upstream` points to `nodepa/seedlingo.git` git remote add upstream [email protected]:nodepa/seedlingo.git git pull --ff upstream main # update main branch to latest upstream version git rebase main -i # rebase onto updated main git push -f # push rebased branch to overwrite remote
-
Get notified when approved and merged.
-
After your pull request is merged, you may want to clean up your fork:
git pull --ff upstream main # update main to latest upstream version git checkout main -f # check out main branch git push origin --delete fix/restore-audio # delete remote branch git branch -D fix/restore-audio # delete local branch
-
Celebrate your successful contribution! 🥳🎉
Note: This section is incomplete.
- TODO: How to start new content?
- TODO: How to pick a license for new content?
- TODO: Add reference to content pack specification in documentation.
- TODO: Possibly remove this section if the suggested idea to publish Seedlingo to NPM without content moves forward, since that will change the model to have separate content projects that use Seedlingo core as a package.
- Check the discussions about content and add your thoughts on the current and desired content generation efforts.
- Check open and closed issues for already suggested content fixes or improvements. Please add a comment to the existing issue instead of opening a new one.
-
Familiarize yourself with Seedlingo's LICENSE. By contributing content to the Seedlingo project, you agree to license your contribution under these terms, and affirm that you have the right to do so.
-
Pick a good first issue or pick one from the prioritized queue on the Development and operations project board, then assign it to yourself or post a comment that you are working on it.
-
If you are not yet a Seedlingo collaborator:
- Fork the Seedlingo repository, then proceed to work on your own fork.
-
Create a new branch off of
main
with a short descriptive name starting withcontent/
, likecontent/cn-relationships
:git checkout -b content/cn-relationships main
-
Find the app's content in the
content/
folder and add your improvements according to the issue you picked. -
Verify the validity of content files by running the
LessonValidation.test.ts
file:npm run test:unit LessonValidation.test.ts
-
Commit your changes using a descriptive commit message that follows our git commit message guidelines:
git config --local commit.template .gitmessage # Add commit template once git add --patch # Add files to staging area git commit # Trigger commit message editor with .gitmessage template
-
Push your branch to GitHub:
git push origin content/cn-relationships
-
Create a pull request describing the aim and scope of the added and/or amended content according to the pull request template.
-
Answer comments on the pull request and await review and approval.
-
Make changes if requested, and commit them to your branch.
-
Rebase your branch on top of later commits to
main
and force push to your GitHub fork, which will update your pull request:git remote -v # Ensure `upstream` points to `nodepa/seedlingo.git` git remote add upstream [email protected]:nodepa/seedlingo.git git pull --ff upstream main # update main branch to latest upstream version git rebase main -i # rebase onto updated main git push -f # push rebased branch to overwrite remote
-
Get notified when approved and merged.
-
After your pull request is merged, you may want to clean up your fork:
git pull --ff upstream main # update main to latest upstream version git checkout main -f # check out main branch git push origin --delete content/cn-relationships # delete remote branch git branch -D content/cn-relationships # delete local branch
-
Celebrate your successful contribution! 🥳🎉
-
Use short sentences and simple language when possible.
-
Use semantic linefeeds in Markdown documents.
-
Aim to use max 80 character wide lines, though shorter is great, too.
-
Complete sentences in lists are capitalized and end with a dot.
-
Incomplete sentences in lists are not capitalized and do not end with a dot.
-
Use Sentence case for headings, because we have to pick one for consistency. Do not use Title Case.
# Sentence case # Title Case <!-- Do not use -->
-
Write GitHub flavoured Markdown.
-
Write in VS Code with Markdown All in One and markdownlint plugins, with the settings in the Seedlingo project's
.vscode/settings.json
file, to keep documentation files similarly formatted.
Git commit messages are documentation, and subject lines may be used to generate change logs.
Our commit message guidelines are inspired by Chris Beams, GloomyCorner and Angular.
Commit message guidelines are provided at commit time
when using the terminal
by adding the .gitmessage
template to your git config:
git config --local commit.template .gitmessage
The full guidelines are available in .gitmessage.
Don't get tempted to include a bug fix and a feature in the same commit.
While the project is set up to lint on commit, notifying you when your code diverges from the style rules, here are a few additional guidelines.
/
- Only the README, LICENSE, .gitmessage, .gitignore and the AWS Amplify config live in the root folder.
/docs/
- All documentation live in
docs/
, with the only exceptions being README and LICENSE files, and some GitHub/process related documentation in.github/
(like CODE_OF_CONDUCT.md and SECURITY.md).
- All documentation live in
/content/
- content files consumed by the app,
including the content's own LICENSE file
covering everything in the
content/
folder
- content files consumed by the app,
including the content's own LICENSE file
covering everything in the
/api/
- backend API
/app/
- home of the frontend/Android app's Vue.js project
/app/android/
- Android related project files
/app/coverage/
- system generated unit test coverage files generated to gauge test coverage
/app/dist/
- system generated production build files
/app/public/
- only for static files that are used directly by
index.html
- only for static files that are used directly by
/app/tests/compontent/
- all unit tests for units that are components
/app/tests/e2e/specs
- all end-to-end tests utilizing Cypress
/app/tests/unit/
- all unit tests for units that are not components
/app/src/
- home of the app's core source code
/app/src/assets/
- relatively static assets, like the app logo
/app/src/ModuleName/
- Each module of the app has its own folder
with a PascalCased/UpperCamelCased name.
BottomNavigationBar
related files live in their own folder, just likeMultipleChoice
andLessons
related files. Content of each module folder should make no assumptions about code living outside of the folder, de-coupling each module from each other. Each module is generally a high-level component with supporting sub-components and logic. - Within module folders,
organize by functionality,
i.e. folders for
components
,data
etc.
- Each module of the app has its own folder
with a PascalCased/UpperCamelCased name.
/app/src/lowercase-named-folders/
- Vue.js features and other common and coupled code live in lowercase named folders.
/app/src/common/
- Functionality re-used by multiple modules should live in the
common/
-folder. Common functionality should preferably be passed into a module when the module is instantiated.
- Functionality re-used by multiple modules should live in the
/app/src/common/animations/
- animations reused across components
/app/src/common/components/
- components reused across the app
/app/src/common/directives/
- custom plugin directives
/app/src/common/router/
- Vue.js
Router
for client side Single-Page Application routing
- Vue.js
/app/src/common/store/
- Vue.js
Store
for client side Single-Page Application state management
- Vue.js
/app/src/common/types/
- shared types
/app/src/test-support/
- assets only used in tests
- overrides for content to allow consistency regardless of content changes
- Because the unit test framework simulates a DOM, some web API objects and functions don't exist in the unit test "browser", so we mock certain functions to prevent tests from failing for environment disparity reasons.
/app/src/views/
- Vue.js
Views
for top-level component containers/pages generally addressed in the router.
- Vue.js
All TypeScript code is linted with ESLint and Prettier.
Trigger lint with npm run lint
.
-
Don't override linting rules, and ask first if you absolutely have to override.
-
Prioritize descriptive variable/method naming over brevity. Aim to make the code readable. Avoid comments if the same information can be conveyed by clever variable/method naming.
-
Capitalize initialisms and acronyms in names, except for the first word, which should be lower-case:
getURI
instead ofgetUri
uriToOpen
instead ofURIToOpen
-
Prefer the object spread operator (
{...anotherObj}
) toObject.assign()
-
Include a single line of whitespace between methods.
-
Use
slice()
to copy an array -
Inline
export
with expressions whenever possible// Use this: export default class ClassName { } // Instead of: class ClassName { } export default ClassName
-
Place instances of
require
in the following order:- Built-in Node Modules (such as
path
) - Local Modules (using relative paths or
@/
shortcut)
- Built-in Node Modules (such as
-
Place class properties in the following order:
- Class methods and properties (methods starting with
static
) - Instance methods and properties
- Class methods and properties (methods starting with
The Seedlingo project, EXCEPT all material in the content/ folder, is licensed to the public under the MIT License.
The Seedlingo project's content/ is licensed to the public under a Creative Commons Attribution-ShareAlike 4.0 International Public License.
By contributing to the Seedlingo project, you agree to license your contribution to the public under these terms, and affirm that you have the right to do so.