Contributions are very welcome! Codidact is an open, community-run project, and that means the code too.
- Bugs are reported here on GitHub. Have a look at the open
issues tagged
type: bugto find something that needs fixing. - Requests for features are first discussed on our meta site to create consensus around their specification. Once consensus is built, a card will be added to our MVP GitHub project as a To Do item.
Once you've picked what you're going to work on, please leave a comment on the issue to indicate you're planning to work on it; this helps us reduce wasted effort. If there's not already an issue for the feature you want to work on, please create one. If you need time to work on an issue, that's absolutely fine, but please keep us updated with comments on the issue - if we don't hear from you for a few weeks, we may assume you've given up working on that issue and give it to someone else.
- First, you need an issue to work under. Either assign yourself to an existing issue (or request it be assigned to you), or create a new issue and assign yourself to that.
- Second, you can make your changes. If you have access to
the repository, create a topic branch (please use the format
art/40/add-bells-and-whistles, i.e.username/issue-number/brief-description) and make your changes there; if not, fork the repository and work in your fork. - Once you've made your changes, submit a pull request targeting
the
developbranch.
Keep in mind that status checks are required to pass and at least one approving review is required from the team before any pull request can be merged. If status checks don't pass, we won't be able to merge - there are no exceptions, so please fix the failures and commit again. You can always mark your pull request as [WIP] (for "Work In Progress") while you're still trying to make it work.
We have code style and standards documents for each applicable language. Please make sure you follow these if possible; if there's a good reason why not, please document it in your code, add a linter exception, and let us know why in your pull request. Here they are:
- Code standards: CSS
- Code standards: CSS naming
- Code standards: HTML
- Code standards: JS
- For C# code standards, please follow the Microsoft style guide.
When writing CSS, keep in mind that our design framework, Co-Design is available in Core, and should be used where possible. Avoid writing custom CSS if you can; favour using components and atomic classes from Co-Design.
Again, please follow these where possible, as they help us to keep a cohesive commit history and see how the project has developed.
The status of this document is currently Request for Comments.
Commit messages are a golden opportunity to give people context on what you are adding to the codebase. These are some guidelines to make sure everyone is using them consistently.
Your subject line (the commit title) should be a concise summary of the changes being submitted. Be specific and precise, and avoid getting into minuteness - additional context, if needed, should be added in the detailed commit description, not here.
Please keep the subject line under 70-75 characters. This encourages conciseness and ensures the summary is rendered fully in a diverse range of environments.
Good:
Add the user's fetch information in a global multidimensional array instead of a local one.
Bad:
Fixed scope bugs.
In most cases - except for the most trivial changes, a commit description (or "body") is necessary to include additional context (such as how and why a certain change - or set thereof - was implemented). Be descriptive and provide as much information as required, while also striving to minimize excessive verbosity.
Commit descriptions can have any arbitrary number of lines, within reason - use your best judgment. Does your description refer only to things that are relevant to the changes being made?
Also note that, unlike the commit summary, there is no restriction imposed on the commit description character length. Here as well, we expect contributors to use their best judgment, by using line breaks and blank lines where it makes sense.
-
Include relevant information and context where you can, to allow us to quickly see the purpose of the commit. Don't be too verbose - be specific and concise.
-
Write in the infinitive, not in the past - i.e. write "Add user details to the global scope and fetch on load" rather than "Added user details to the global scope and fetched on load"
-
The use of standard markdown is allowed, but we prefer plain text. Use single quotes to refer to specific filenames or code snippets within the commit message (i.e.
404 error page: Fix conflicting 'margin' CSS property for 'body'). If using markdown, refer to a syntax cheatsheet if necessary. -
Use short commit hashes whenever you need to refer to previous commits from your commit message. The short hash should preferably have a length of 8; a length of 7 is also acceptable. Example:
Complements 17236a81 by adding line break.
Note that the GitHub interface will always render commit hashes abbreviated to 7 chars.
If your change is small enough to not have a commit body, i.e. your subject line can describe your changes, then it's okay to commit without one. If you're making significant changes that require more explanation then you must include the commit body.
Each commit you make should do one thing. Try to make sure all changes in the commit are all for the same purpose - one refactoring, or one feature, etc. If you have more changes to make, split them up into multiple commits.
Commits on development branches need not pass tests every time. Particularly if you're writing your tests first and then developing features, it can be helpful to create a commit where tests don't pass.
Merges and commits to master must pass the tests every time. The master branch is considered the stable channel - anything on there should be suitable for production deployment. Commits should generally not be made directly to master - only organization and repository administrators have the ability to, and should avoid doing so if at all possible.