From 52e9089e14bb5ad516b900718569fc03bd590a15 Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Sun, 19 Nov 2023 21:00:44 +0000 Subject: [PATCH] build based on fd77f92 --- dev/.documenter-siteinfo.json | 2 +- dev/index.html | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/dev/.documenter-siteinfo.json b/dev/.documenter-siteinfo.json index 9613dfa..db03a5d 100644 --- a/dev/.documenter-siteinfo.json +++ b/dev/.documenter-siteinfo.json @@ -1 +1 @@ -{"documenter":{"julia_version":"1.9.4","generation_timestamp":"2023-11-19T20:59:51","documenter_version":"1.1.2"}} \ No newline at end of file +{"documenter":{"julia_version":"1.9.4","generation_timestamp":"2023-11-19T21:00:41","documenter_version":"1.1.2"}} \ No newline at end of file diff --git a/dev/index.html b/dev/index.html index df6466c..5d11c56 100644 --- a/dev/index.html +++ b/dev/index.html @@ -1,5 +1,5 @@ -SciML Style Guide for Julia · SciML Style Guide for Julia
GitHub

SciML Style Guide for Julia

SciML Code Style Global Docs

The SciML Style Guide is a style guide for the Julia programming language. It is used by the SciML Open Source Scientific Machine Learning Organization. As such, it is open to discussion with the community. Please file an issue or open a PR to discuss changes to the style guide.

Table of Contents

Code Style Badge

Let contributors know your project is following the SciML Style Guide by adding the badge to your README.md.

[![SciML Code Style](https://img.shields.io/static/v1?label=code%20style&message=SciML&color=9558b2&labelColor=389826)](https://github.com/SciML/SciMLStyle)

Overarching Dogmas of the SciML Style

Consistency vs Adherence

According to PEP8:

A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is the most important.

But most importantly: know when to be inconsistent – sometimes the style guide just doesn't apply. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don't hesitate to ask!

Some code within the SciML organization is old, on life support, donated by researchers to be maintained. Consistency is the number one goal, so updating to match the style guide should happen on a repo-by-repo basis, i.e. do not update one file to match the style guide (leaving all other files behind).

Community Contribution Guidelines

For a comprehensive set of community contribution guidelines, refer to ColPrac. A relevant point to highlight PRs should do one thing. In the context of style, this means that PRs that update the style of a package's code should not be mixed with fundamental code contributions. This separation makes it easier to ensure that large style improvements are isolated from substantive (and potentially breaking) code changes.

Open source contributions are allowed to start small and grow over time

If the standard for code contributions is that every PR needs to support every possible input type that anyone can think of, the barrier would be too high for newcomers. Instead, the principle is to be as correct as possible to begin with, and grow the generic support over time. All recommended functionality should be tested, and any known generality issues should be documented in an issue (and with a @test_broken test when possible). However, a function that is known to not be GPU-compatible is not grounds to block merging, rather it is encouraged for a follow-up PR to improve the general type support!

Generic code is preferred unless code is known to be specific

For example, the code:

function f(A, B)
+SciML Style Guide for Julia · SciML Style Guide for Julia
GitHub
SciML Style Guide for Julia
SciML Code Style Global Docs
The SciML Style Guide is a style guide for the Julia programming language. It is used by the SciML Open Source Scientific Machine Learning Organization. As such, it is open to discussion with the community. Please file an issue or open a PR to discuss changes to the style guide.
Table of Contents
Code Style Badge
Let contributors know your project is following the SciML Style Guide by adding the badge to your README.md.
[![SciML Code Style](https://img.shields.io/static/v1?label=code%20style&message=SciML&color=9558b2&labelColor=389826)](https://github.com/SciML/SciMLStyle)
Overarching Dogmas of the SciML Style
Consistency vs Adherence
According to PEP8:
A style guide is about consistency. Consistency with this style guide is important. Consistency within a project is more important. Consistency within one module or function is the most important.
But most importantly: know when to be inconsistent – sometimes the style guide just doesn't apply. When in doubt, use your best judgment. Look at other examples and decide what looks best. And don't hesitate to ask!
Some code within the SciML organization is old, on life support, donated by researchers to be maintained. Consistency is the number one goal, so updating to match the style guide should happen on a repo-by-repo basis, i.e. do not update one file to match the style guide (leaving all other files behind).
Community Contribution Guidelines
For a comprehensive set of community contribution guidelines, refer to ColPrac. A relevant point to highlight PRs should do one thing. In the context of style, this means that PRs that update the style of a package's code should not be mixed with fundamental code contributions. This separation makes it easier to ensure that large style improvements are isolated from substantive (and potentially breaking) code changes.
Open source contributions are allowed to start small and grow over time
If the standard for code contributions is that every PR needs to support every possible input type that anyone can think of, the barrier would be too high for newcomers. Instead, the principle is to be as correct as possible to begin with, and grow the generic support over time. All recommended functionality should be tested, and any known generality issues should be documented in an issue (and with a @test_broken test when possible). However, a function that is known to not be GPU-compatible is not grounds to block merging, rather it is encouraged for a follow-up PR to improve the general type support!
Generic code is preferred unless code is known to be specific
For example, the code:
function f(A, B)
     for i in 1:length(A)
         A[i] = A[i] + B[i]
     end
@@ -261,4 +261,4 @@
         "files.eol": "\n"
     },
 }
Additionally, you may find the Julia VS-Code plugin useful.
JuliaFormatter
Note: the sciml style is only available in JuliaFormatter v1.0 or later
One can add .JuliaFormatter.toml with the content
style = "sciml"
in the root of a repository, and run
using JuliaFormatter, SomePackage
-format(joinpath(dirname(pathof(SomePackage)), ".."))
to format the package automatically.
Add FormatCheck.yml to enable the formatting CI. The CI will fail if the repository needs additional formatting. Thus, one should run format before committing.
References
Many of these style choices were derived from the Julia style guide, the YASGuide, and the Blue style guide. Additionally, many tips and requirements from the JuliaHub Secure Coding Practices manual were incorporated into this style.

+format(joinpath(dirname(pathof(SomePackage)), ".."))

to format the package automatically.

Add FormatCheck.yml to enable the formatting CI. The CI will fail if the repository needs additional formatting. Thus, one should run format before committing.

References

Many of these style choices were derived from the Julia style guide, the YASGuide, and the Blue style guide. Additionally, many tips and requirements from the JuliaHub Secure Coding Practices manual were incorporated into this style.