From 06109001f8f8d2fce2fa2f75bb386f410c7df112 Mon Sep 17 00:00:00 2001 From: Rob Purser Date: Tue, 6 Jun 2023 08:25:13 -0400 Subject: [PATCH 1/7] Add language that this is a work in progress --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 0174a6b..74110e5 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,13 @@ # MATLAB Toolbox Best Practices -![](https://img.shields.io/github/v/release/mathworks/toolboxdesign?label=version) ![](https://img.shields.io/github/license/mathworks/toolboxdesign) +![Version Number](https://img.shields.io/github/v/release/mathworks/toolboxdesign?label=version) ![CC-BY-4.0 License](https://img.shields.io/github/license/mathworks/toolboxdesign) You have a MATLAB® toolbox that you want to share with the world. We want to help. To do that, we want to convince you to use the MathWorks Toolbox best practices. It's a little bit of extra work with a big payoff. Being in a standard format makes it easier for other people to assess and take advantage of your work. Your work is more "legible," because it's in a familiar format. They know, for example, that they can always expect to find a helpful and thorough `README.md` file in the top folder. They also know that a good place to start learning how to use your toolbox will be the `gettingStarted.mlx` file. These and other best practices help your users build confidence that your toolbox is well built and ready to use. +This is a continuously evolving document and some best practices may change in the future as MATLAB evolves. We encourage your feedback and suggestions for future revisions. Feel free to [open an issue](https://github.com/mathworks/toolboxdesign/issues) or [post to the discussions](https://github.com/mathworks/toolboxdesign/discussions). Your insights and feedback help us improve this document and make it even more useful for the community. + But the advantages go beyond helping your users. Standard formats also make it easier for you to maintain the toolbox. Tools and systems (such as automated testing on GitHub) will immediately know how to work. We use the term “toolbox” here to mean a collection of reusable MATLAB code that you want to share with other people. Toolboxes contain not just code files, but also data, apps, tests, and examples. Some toolboxes will be just a few files; others may be extensive and represent years of effort by multiple people. The guidelines we present can be adapted for toolboxes that are large or small, casual or sophisticated. We will step through a comprehensive example with many aspects. There’s no need to do everything all at once -- you can start with a few guidelines and adopt more as you go. From c23b6b4747b7a2660d0f37916e21599533798650 Mon Sep 17 00:00:00 2001 From: Rob Purser Date: Tue, 6 Jun 2023 08:27:09 -0400 Subject: [PATCH 2/7] Moved the new text up --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 74110e5..b6518d2 100644 --- a/README.md +++ b/README.md @@ -4,10 +4,10 @@ You have a MATLAB® toolbox that you want to share with the world. We want to help. To do that, we want to convince you to use the MathWorks Toolbox best practices. It's a little bit of extra work with a big payoff. -Being in a standard format makes it easier for other people to assess and take advantage of your work. Your work is more "legible," because it's in a familiar format. They know, for example, that they can always expect to find a helpful and thorough `README.md` file in the top folder. They also know that a good place to start learning how to use your toolbox will be the `gettingStarted.mlx` file. These and other best practices help your users build confidence that your toolbox is well built and ready to use. - This is a continuously evolving document and some best practices may change in the future as MATLAB evolves. We encourage your feedback and suggestions for future revisions. Feel free to [open an issue](https://github.com/mathworks/toolboxdesign/issues) or [post to the discussions](https://github.com/mathworks/toolboxdesign/discussions). Your insights and feedback help us improve this document and make it even more useful for the community. +Being in a standard format makes it easier for other people to assess and take advantage of your work. Your work is more "legible," because it's in a familiar format. They know, for example, that they can always expect to find a helpful and thorough `README.md` file in the top folder. They also know that a good place to start learning how to use your toolbox will be the `gettingStarted.mlx` file. These and other best practices help your users build confidence that your toolbox is well built and ready to use. + But the advantages go beyond helping your users. Standard formats also make it easier for you to maintain the toolbox. Tools and systems (such as automated testing on GitHub) will immediately know how to work. We use the term “toolbox” here to mean a collection of reusable MATLAB code that you want to share with other people. Toolboxes contain not just code files, but also data, apps, tests, and examples. Some toolboxes will be just a few files; others may be extensive and represent years of effort by multiple people. The guidelines we present can be adapted for toolboxes that are large or small, casual or sophisticated. We will step through a comprehensive example with many aspects. There’s no need to do everything all at once -- you can start with a few guidelines and adopt more as you go. From 8dda7144e5497efad69cbd38f7e64ae3e71710bb Mon Sep 17 00:00:00 2001 From: Rob Purser Date: Tue, 6 Jun 2023 19:58:06 -0400 Subject: [PATCH 3/7] Create check.yml Going to add spell check, link check, and markdown check --- .github/workflows/check.yml | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 .github/workflows/check.yml diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml new file mode 100644 index 0000000..7f7068d --- /dev/null +++ b/.github/workflows/check.yml @@ -0,0 +1,25 @@ +name: Check + +# Controls when the workflow will run +on: + # Triggers the workflow on push or pull request events but only for the "main" branch + push: + branches: [ "v1.0.0-wip" ] + pull_request: + branches: [ "main" ] + + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +jobs: + check: + runs-on: ubuntu-latest + + steps: + # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it + - uses: actions/checkout@v3 + + # Runs a single command using the runners shell + - name: Run a one-line script + run: echo Hello, world! + From 6c5a977158ac7684a4cd028e77a60e01213d0bbe Mon Sep 17 00:00:00 2001 From: Rob Purser Date: Tue, 6 Jun 2023 20:04:29 -0400 Subject: [PATCH 4/7] Try spellcheck --- .github/workflows/check.yml | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index 7f7068d..a424951 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -19,7 +19,9 @@ jobs: # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - uses: actions/checkout@v3 - # Runs a single command using the runners shell - - name: Run a one-line script - run: echo Hello, world! + - uses: rojopolis/spellcheck-github-actions@v0 + name: Spellcheck + with: + source_files: README.md + From 42e159de1b82304cb1eeaca647e5c652ee658b94 Mon Sep 17 00:00:00 2001 From: Rob Purser Date: Tue, 6 Jun 2023 20:06:29 -0400 Subject: [PATCH 5/7] working on spellcheck --- .github/workflows/check.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml index a424951..2895dd3 100644 --- a/.github/workflows/check.yml +++ b/.github/workflows/check.yml @@ -21,7 +21,6 @@ jobs: - uses: rojopolis/spellcheck-github-actions@v0 name: Spellcheck - with: - source_files: README.md + From 2a39a22a536275dbe316aabc52694b1d8213a81b Mon Sep 17 00:00:00 2001 From: Rob Purser Date: Wed, 7 Jun 2023 06:22:05 -0400 Subject: [PATCH 6/7] Moved spellcheck work to its own branch --- .github/workflows/check.yml | 26 -------------------------- 1 file changed, 26 deletions(-) delete mode 100644 .github/workflows/check.yml diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml deleted file mode 100644 index 2895dd3..0000000 --- a/.github/workflows/check.yml +++ /dev/null @@ -1,26 +0,0 @@ -name: Check - -# Controls when the workflow will run -on: - # Triggers the workflow on push or pull request events but only for the "main" branch - push: - branches: [ "v1.0.0-wip" ] - pull_request: - branches: [ "main" ] - - # Allows you to run this workflow manually from the Actions tab - workflow_dispatch: - -jobs: - check: - runs-on: ubuntu-latest - - steps: - # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it - - uses: actions/checkout@v3 - - - uses: rojopolis/spellcheck-github-actions@v0 - name: Spellcheck - - - From 289e5919e92d4ecc6d41a15793ed2d8d87c590ad Mon Sep 17 00:00:00 2001 From: Rob Purser Date: Wed, 7 Jun 2023 12:31:07 -0400 Subject: [PATCH 7/7] Add language about plans to address workflows with build step. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b6518d2..c69b621 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ You have a MATLAB® toolbox that you want to share with the world. We want to help. To do that, we want to convince you to use the MathWorks Toolbox best practices. It's a little bit of extra work with a big payoff. -This is a continuously evolving document and some best practices may change in the future as MATLAB evolves. We encourage your feedback and suggestions for future revisions. Feel free to [open an issue](https://github.com/mathworks/toolboxdesign/issues) or [post to the discussions](https://github.com/mathworks/toolboxdesign/discussions). Your insights and feedback help us improve this document and make it even more useful for the community. +This is a continuously evolving document and some best practices may change in the future as MATLAB evolves. We encourage your feedback and suggestions for future revisions. Feel free to [open an issue](https://github.com/mathworks/toolboxdesign/issues) or [post to the discussions](https://github.com/mathworks/toolboxdesign/discussions). Your insights and feedback help us improve this document and make it even more useful for the community. Right now, we're focused on toolboxes that don't have derived files that require a build step, like MEX files or content-obscured files (P-Code). We plan to address those in the future. Being in a standard format makes it easier for other people to assess and take advantage of your work. Your work is more "legible," because it's in a familiar format. They know, for example, that they can always expect to find a helpful and thorough `README.md` file in the top folder. They also know that a good place to start learning how to use your toolbox will be the `gettingStarted.mlx` file. These and other best practices help your users build confidence that your toolbox is well built and ready to use.