Contributing

Contributing to Blazorise

We welcome contributions and any suggestions or feature requests you might have. Contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to and actually do, grant us the rights to use your contribution. This will be signed once you submit a PullRequest on our repository. For details about our CLA, please visit https://gist.github.com/stsrki/abfa5ce0f4a5cf1e6ac67b92f8eb5d63

Getting Started

Please visit https://github.com/Megabit/Blazorise/blob/master/CONTRIBUTING.md to learn how to set up the required steps to contribute.

Conventions && Guidelines

To reduce code complexity and improve readability we ask that you follow our repository conventions and guidelines when submitting a pull request. We will not refuse your pull request, however, we may ask you that you review it, if it does not adhere to the conventions and guidelines.

In order to keep improving our code base and keep up to date with modern practices, the following guidelines aren't set in stone and may change over time by refactoring the code base. We do take suggestions.

Formatting

If possible, adhere to the provided .editorconfig formatting rules.

Coding conventions

Naming

• Private fields : Camel Case
  • private string exampleField
• Methods : Pascal Case
  • private void ExampleMethod()
• Properties : Pascal Case
  • public string ExampleField { get; set; }
• Constants : Upper case, separate words with underscore
  • public const string EXAMPLE_CONSTANT
• Variables : Camel Case
  • var exampleVariable

Coding

• Prefer is null and is not null over == null and != null
• Prefer prefixless booleans for regular properties, for example: Loading over IsLoading
  • Exception is when you provide a property getter, then it's good practice to prefix it, for example: IsLoading => Options?.Loading ?? Loading ?? false;
• Prefer null propagation: https://docs.microsoft.com/en-us/dotnet/fundamentals/code-analysis/style-rules/ide0031
• Prefer target-typed new : https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/proposals/csharp-9.0/target-typed-new

Blazorise plans to have RTL (Right To Left) support, as such, when coding layout-related APIs, it's preferred to use Start over Left and End over Right, as those are terms that can be better used interchangeably between both LTR and RTL modes.

Blazor

When working with blazor components, it is preferred to separate the component into two files

• TextEdit.razor (Mostly markup concerns and rendering/styling logic)
• TextEdit.razor.cs (All the members, parameters, and logic that make the component work) - can be referred as code-behind

We keep the main sections of our code-behind components separated by regions, please adhere to the following class template:

public partial class MyComponent : BaseComponent
{
  #region Members

  #endregion

  #region Constructors

  #endregion

  #region Methods

  #endregion

  #region Properties

  #endregion
}

Render Fragments

Preferably, these should be suffixed *Template. ex: ItemTemplate, LoadingTemplate

Blazorise styling:

• For component CSS prefer: b-{component} instead of b-is-{component}
• When working with classes and styling, the various providers must be taken into account, and if some styling or class may be different across providers, the ClassProvider and StyleProvider abstractions should be used.

Blazorise css naming:

Try to stick with the naming or convention of any 3rd party library if applicable. The b- prefix naming convention should be used only in Blazorise.csproj, a core library. This is because in there we don't have any knowledge of which CSS framework is running. So we add a prefix to make it more explicit.

Public APIs

Please do not change any public facing API in a way that it can break the consumer's code. These changes can be suggested, and should be carefully considered and integrated into a major release (i.e v1.0 / v2.0 / v3.0 and so on...). Any APIs that should be removed, should be first made Obsolete with the explicit reason and removed only in the next major release.