GithubHelp home page GithubHelp logo

nasa-ammos / slim Goto Github PK

View Code? Open in Web Editor NEW
24.0 8.0 9.0 11.66 MB

Software Lifecycle Improvement & Modernization

Home Page: https://nasa-ammos.github.io/slim/

License: Apache License 2.0

JavaScript 71.65% MDX 2.00% CSS 26.35%
documentation governance jpl lifecycles nasa

slim's Introduction


SLIM Logo

Software Lifecycle Improvement & Modernization (SLIM)

A shared community resource for discussing, iterating and referencing a common set of best practices in software development standards for NASA multi-mission space and ground software.

SLIM

screen-slim

This repository hosts the SLIM website, a project aimed at developing a common set of best practices in software development standards for NASA multi-mission space and ground software. The website leverages Docusaurus 2, a static website generator.

Website | Discussion Board | Issue Tracker

Features

  • Community-developed best practices and recommendations for software development encoded as Markdown guides
  • Static content for the SLIM website, including live preview during local development, and deployment support for GitHub pages hosting

Contents

Quick Start

To get started with the SLIM project website (including developing and building / deploying it), please follow the steps below.

Requirements

  • Node.js 12 or higher
  • Yarn package manager

Setup Instructions

  1. Clone the repository
  2. Navigate into the directory
  3. Run yarn to install dependencies

Run Instructions

  1. Run yarn start to start a local development server
  2. The command should open a browser window with the website running

Usage Examples

  • After making changes to the website, you can see them reflected live in your browser without having to restart the server.

Build Instructions

  1. Run yarn build to generate static content into the build directory

Test Instructions

  1. After building, the website can be served using any static contents hosting service.

Changelog

See our CHANGELOG.md for a history of our changes.

See our releases page for our key versioned releases.

Frequently Asked Questions (FAQ)

Ask us a question in our discussion board. We'll migrate common questions here.

Contributing

Please refer to the following resources for more information on contributing:

  • To learn how to contribute to our project, please consult our Contributing Guide.
  • To understand the community ideals and policies we adhere to, please review our Code of Conduct.
  • For insights into the governance model that governs our project, please refer to our Governance Model.

License

Please refer to our LICENSE for details regarding the licensing terms and conditions of our project.

Support

For inquiries regarding support, please reach out to the members of our Technical Steering Committee. They will be able to provide you with the necessary information and assistance.


slim's People

Contributors

ddalton-swe avatar dependabot[bot] avatar ewferg avatar github-actions[bot] avatar ingyhere avatar jpl-jengelke avatar mike-gangl avatar perryzjc avatar riverma avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

slim's Issues

[New Website Feature]: Simplify SLIM best practice guides

Checked for duplicates

Yes - I've already checked

Alternatives considered

Yes - and alternatives don't suffice

Related problems

As mentioned by @tariqksoliman et al in #36 as well as other discussions with folks like @darth-pr a few months back, the SLIM best practice guides are a bit complex to sift through for new folks. They have quite a few pages to go through and that adds complexity.

Moreover, the prime interest in users of SLIM so far has tended to be Starter Kits, which are a bit buried in the documentation.

Describe the feature request

Let's try and simply the organization / structure of the SLIM best practice guides.

Right now, for example the "Documentation Guide" has the following structure:

  • Use Cases
  • Trade Studies
  • Reference Architectures
  • Starter Kits

Can we simplify the above to something more interactive and use case oriented? RETYPE has a feature called "stacked panels" which we could leverage as a set of initial questions for pointing people to specific resources we're offering.

Per @tariqksoliman's suggestion, I'm thinking we simplify the whole best practice guide structure to the following only:

  1. A set of stacked panels for resources people might be interested in. For example: "I'm looking for templates", or "I'm looking for tools", etc. These panel provide a set of links to resources in step 2 below.
  2. A single page with all resources provided and anchor-linked for quick reference

Open to other ideas!

Use Case links back to Github return errors from Website:

Checked for duplicates

Yes - I've already checked

Website or Best Practice Guide?

Website

Describe the bug

When I clicked the "Coverage" link under the Python branch, I noticed that the page did not resolve and an error appeared, "github.com refused to connect". this only happens with links that go back to Github.com

What did you expect?

I expected the link to open a new Web page.

Reproducible steps

1. Open the SLIM Web site at https://nasa-ammos.github.io/slim/
2. Within Continuous Testing section, select Use Cases
3. Navigate to All Use Cases, "preview of mind map" and scroll to expand the chart.
4. In the chart click on Continuous Testing -> For Code Analysis -> For Dynamic Analysis -> For Test Coverage -> Using Python -> Using Coverage.
5. Page does not load and the error appears.
...

Environment

- Chrome 100.0.4896.127
- Operating System: [e.g. MacOSX 10.6.5 (Big Sur update)]

[Improve Existing Best Practice Guide]: CI Architectural Reference Guide Diagram Clipping Issues

Checked for duplicates

Yes - I've already checked

Best Practice Guide

Continuous Integration

Best Practice Guide Sections

Reference Architectures

Describe the improvement

The Mermaid diagrams have clipped text that doesn't ready fully. This is present in both GitHub view as well as the rendered RETYPE webpage view. Attached is an example. Additionally the "A series of systems executing builds" diagram is not rendering the bold-typed text properly (picture attached).
Screen Shot 2022-09-15 at 4 25 35 PM
Screen Shot 2022-09-15 at 4 26 23 PM

[Improve Best Practice Guide]: Continuous integration (RA) through Jenkins, et. al.

Checked for duplicates

Yes - I've already checked

Best Practice Guide

Continuous Integration

Best Practice Guide Sections

  • Use Cases
  • Trade Studies
  • Reference Architectures
  • Starter Kits

Describe the improvement

We need a reference architecture diagram for building and deploying a project to Artifactory.

This and another item were reflected previously in the R1 change log but were delayed to address concerns raised during code reviews.

[Improve Best Practice Guide]: Continuous integration (SK) through Jenkins, et. al.

Checked for duplicates

Yes - I've already checked

Best Practice Guide

Continuous Integration

Best Practice Guide Sections

  • Use Cases
  • Trade Studies
  • Reference Architectures
  • Starter Kits

Describe the improvement

We need a starter kit for Jenkins project setup / configuration (user guide).

This and another item were reflected previously in the R1 change log but were delayed to address concerns raised during code reviews.

[Improve Existing Best Practice Guide]: Documentation Guide Additional Material

Checked for duplicates

Yes - I've already checked

Best Practice Guide

Documentation

Best Practice Guide Sections

No response

Describe the improvement

We need additional use cases and material for:

  • Best practices for hosting training guides (+1'd by @ramesh-maddegoda @LucaCinquini @galenatjpl)
  • Consistent and single-point-of-entry for all software documentation (+1'd by mcduffie)
  • Best practices for on-boarding new users / developers (+1'd by @ramesh-maddegoda)
  • Hand-off between manual and automated processes

[New Website Feature]: Automation to send pull-requests

Checked for duplicates

Yes - I've already checked

Alternatives considered

No - I haven't considered

Related problems

As we build up a set of process improvement solutions, the hard part of infusing these improvements to member projects comes to mind. One way @riverma has navigated this is to leverage a tool called multi-gitter to send out PRs for key deliverables that have been made to SLIM member project repositories. The issue is that only @riverma currently has a local setup to run this tool, and also has to replicate all of the delivered artifacts locally (e.g. templates, starter kits) locally to push them out.

Describe the feature request

Can we send PR's for our SLIM best practices in a more transparent, community-oriented way?

Some ideas:

  • Create a GitHub Actions Workflow that is invoked manually to create PRs for a given SLIM deliverable towards a given set of repositories
  • Train the SLIM contributors to be able to use multi-gitter like @riverma does
  • Create a GitHub Actions Bot that checks for new best practice solutions from SLIM and creates tickets on a given repository when new items are available (members would have to install this bot)

[New Process Improvement Need]: Third-Party Software Vetting

Checked for duplicates

Yes - I've already checked

Category

Security - application, network, hardware, etc. security topics

Describe the need

We have a need for a more defined process for vetting and managing 3rd-party software installed in development and deployment environments. (+1'd by mcduffie)

Markmap diagram does not always regenerate on GitHub Pages rendering

Checked for duplicates

Yes - I've already checked

Describe the bug

When pushing changes to a respective *markmap.md file to GitHub, sometimes the equivalent *markmap.html version appears to be out-of-date on the GitHub Pages. This behavior is non-deterministic - sometimes the *markmap.html gets regenerated on the GitHub Pages website, whereas sometimes it does not get regenerated.

The way to confirm a discrepancy is to check the contents of the *markmap.html file between the main and the retype branches on the repository. It seems the order of GitHub automated workflows for the regeneration of the Markmap file and the GH website is non-deterministic.

What did you expect?

I expect every commit / push to a *markmap.md document to GitHub to trigger an automatic re-generation of the equivalent *markmap.html file via the markmap GitHub workflow followed by a re-generation of the GitHub Pages website via the re-type GitHub workflow. Ensuring the order of the above is essential.

Reproducible steps

  1. Make local changes to a *markmap.md file
  2. Push to GitHub
  3. Monitor for equivalent changes to appear in *markmap.html version on the website: https://nasa-ammos.github.io/slim
  4. You may notice the *markmap.html is out-of-date w.r.t the *markmap.md file

Environment

N/A

[Improve Existing Best Practice Guide]: Validating software dependencies (CT starter kit) using dependabot

Checked for duplicates

Yes - I've already checked

Describe the needs

This is intended for the Continuous Testing Starter Kit.

It's desirable for OSS publishers to implement automatic security and bug scanning of software dependencies used within their repo. This SK will provide a guide on implementing basic dependabot checking for a software project with configurable options. It's GitHub Actions-based process that will be helped with a simple template.

[New Process Improvement Need]: Triaging Change Requests

Checked for duplicates

Yes - I've already checked

Category

Information Sharing - documentation design, templates, communication, etc.

Describe the need

We have a need for better guidance / standards for:

  • Triaging Strategy for New Issue Tickets (+1'd by @kgrimes2)
  • Governance approach for acceptance / rejection of proposed software changes
  • Dynamic change-management process (make it quick to decide on swapping out or adding a new A&A system, etc.)
  • Governance approach for vetting and integrating outside contributions to open source projects (+1'd by @ngachung)
  • Governance approach for handling feature requests and community-based decision making.
  • Governance approach for creating / modifying core software documentation

[New Process Improvement Need]: Recommendations for automated security scans

Checked for duplicates

Yes - I've already checked

Category

Security - application, network, hardware, etc. security topics

Describe the need

We have a need for:

  • Guidance for repository security scanning (+1'd by @ramesh-maddegoda)
  • Automated source code quality scanning tools (E.g.: SonarCube)  to check the source code quality
  • Automated static security scanning tools (E.g: HP Fortify, IBM AppScan) to check source code for security vulnerabilities
  • Automated 3rd party dependency scanning tools (E.g: Back Duck) to ensure if the algorithms are not using known vulnerable open source libraries

[Improve Best Practice Guide]: Starter kits for patch integrity

Checked for duplicates

Yes - I've already checked

Best Practice Guide

Continuous Integration

Best Practice Guide Sections

  • Use Cases
  • Trade Studies
  • Reference Architectures
  • Starter Kits

Describe the improvement

I'd like to include starter kits for better enforcement of patch integrity, specifically starter kits for checking for unauthorized credential commits (thanks @mike-gangl) as well as ensuring we have some guidance on enforcing Developer Certificate of Origin (DCO) requirements (as spelled out in our Documentation -> Contribution Guide template).

[Improve Existing Best Practice Guide]: Contributing guide should outline guidance for gov't folks on posting public content

Checked for duplicates

Yes - I've already checked

Best Practice Guide

Documentation

Best Practice Guide Sections

Starter Kits

Describe the improvement

We've received questions and passed out guidance on how to converse in open source tickets / discussion boards when some of the operational software systems are not publicly accessible. We've noticed sometimes that SLIM community members post internal intra-net hyperlinks (only accessible to their institution) or snippets that include sensitive info like IPs. Guidance here would help serve as a reference for all.

[Improve Existing Best Practice Guide]: Guidance on choosing a documentation hosting solution

Checked for duplicates

Yes - I've already checked

Best Practice Guide

Documentation

Best Practice Guide Sections

Trade Studies

Describe the improvement

We've gotten input from folks that they have a need for choosing a best documentation hosting solution, as well as how to get started with it. Currently, we have a table of tools to choose from but its fairly bare bones and difficult to interpret. Let's make this easier: https://nasa-ammos.github.io/slim/documentation/trade-studies/

[New Process Improvement Need]: Blue/Green Deployment Guidance

Checked for duplicates

Yes - I've already checked

Category

Software Lifecycle - the creation, change, and release of software

Describe the need

We have a need for readers to understand best practices for blue/green deployments, especially on cloud infrastructure. For example:

  • What are recommended tools to support blue/green deployments of software stacks?
  • Is there a starter kit to use to support?

[Improve Best Practice Guide]: Unit testing, et. al.

Checked for duplicates

Yes - I've already checked

Best Practice Guide

Continuous Testing

Best Practice Guide Sections

  • Use Cases
  • Trade Studies
  • Reference Architectures
  • Starter Kits

Describe the improvement

We'd like to have starter kits for helping the SLIM community with getting a JUnit or PyUnit testing framework up and running, by providing real world example templates to customize and start using. Additionally, having an architectural reference diagram explaining how Java unit test using JUnit in Jenkins would ideally work would be great. These two were mentioned in previous changelog reports, but were pushed to be done later.

[New Process Improvement Need]: Best Practices for Continuous Deployment/Delivery

Checked for duplicates

Yes - I've already checked

Category

Software Lifecycle - the creation, change, and release of software

Describe the need

We have a need for:

Infusion of git-secrets

Checked for duplicates

Yes - I've already checked

Alternatives considered

Yes - and alternatives don't suffice

Describe the request

We've created a best practice solution for automatically checking for git commits locally for passwords prior to pushing commits to a public repository: https://nasa-ammos.github.io/slim/continuous-integration/starter-kits/#git-secrets. There's a number of projects interested in utilizing these templates, so this ticket tracks that infusion need.

Error in Markmap Action: Failure when no changes required for commits

Checked for duplicates

Yes - I've already checked

Website or Best Practice Guide?

Website

Describe the bug

When a release is performed, automation regenerates Markmap markup for publication to the SLIM website. When an .md file changes anywhere in the repository tree, the action is triggered. When no markmap-generated files change, no commit is made to the repository and the action fails. The failure is precipitated by Git not finding any files to re-commit to the repository. This is an erroneous failure.

What did you expect?

Git should detect when there are no commits and the script should exit gracefully with a success exit code since that is performing as expected.

Reproducible steps

1. Change a markdown file, like `CHANGELOG.md`.
2. Perform a product tag/release.
3. Check the Actions tab to see a failed markmap action.

Environment

- GitHub `ubuntu-latest`
- Node 16 per recent GitHub requirements changes -- see https://github.blog/changelog/2022-09-22-github-actions-all-actions-will-begin-running-on-node16-instead-of-node12/

Infusion of DCO

Checked for duplicates

Yes - I've already checked

Alternatives considered

Yes - and alternatives don't suffice

Describe the request

We've created a best practice solution for automatically checking for developer certificates of origin: https://nasa-ammos.github.io/slim/continuous-integration/starter-kits/#developer-certificate-of-origin-dco. This is particularly useful for ensuring new contributions to open source projects are legally acceptable (i.e. the author has fully accepted the transfer of IP to the OSS project).

[New Process Improvement Need]: Artifact packaging hosting and dependency management

Checked for duplicates

Yes - I've already checked

Category

Software Lifecycle - the creation, change, and release of software

Describe the need

We have a need for recommendations for choice of packaging host (GH Packages, DockerHub, etc.), including automation architecture / solutions for inclusion of dependencies into builds. (+1'd by @mike-gangl). One of the things that would be great here is specific choice of, and details of how to interact with packaging hosts / managers.

[New Process Improvement Need]: Open access tool alternatives

Checked for duplicates

Yes - I've already checked

Category

Software Lifecycle - the creation, change, and release of software

Describe the need

We have a need for recommendations for open access process tool alternatives to locked-down JPL institutional ones. e.g. TestRail

+1'd by @lajewell

[New Process Improvement Need]: Best Practices on Training Material Curation & Sharing

Checked for duplicates

Yes - I've already checked

Category

Information Sharing - documentation design, templates, communication, etc.

Describe the need

We have a need for:

  • Best practices for organizing and making accessible training material for evolving technological trends
  • Best practices for organizing and accessing training materials on containerizing and developing PGEs (+1'd by @LucaCinquini)
  • Process for linking to curated training guides, e.g. cloud training (+1'd by @LucaCinquini @nttoole)
  • "Get started" pages for different kinds of app development (archetypes) (+1'd by @mcduffie @nttoole)

[Improve Existing Best Practice Guide]: Documentation Organization Ref Architecture

Checked for duplicates

Yes - I've already checked

Best Practice Guide

Documentation

Best Practice Guide Sections

Reference Architectures

Describe the improvement

We need some sample reference architectures for recommending how documentation created for a project should be organized. This involves documentation artifacts like user guides, dev guides, etc., and how they can be organized to make it most efficient for users and developers to find those resources.

Documentation SK README: Malformed HTML

Checked for duplicates

Yes - I've already checked

Website or Best Practice Guide?

Best Practice Guide

Describe the bug

When I edited the documentation starter kit README.md file, I was alerted that some html tags were deprecated or unsupported.
malformed_tags

What did you expect?

I expected no errors when editing the markdown using an IDE.

However, the IDE reported the following concerns:

  1. Line 4: <div align="center"> -- Obsolete attribute (deprecated)
  2. Line 10: <h1 align="center"> -- Obsolete attribute (deprecated)
  3. Line 15: <pre align="center"> -- Attribute align is not allowed here.

Reproducible steps

1. Open the `README-sw-proj-template.md` file in a static HTML5 language checker, like that built-in to the `PyCharm` IDE. 

PyCharm inspects HTML files to conform to the final W3C HTML5 specification.

Environment

- PyCharm 2022.2.3 / htmlparser2

[New Website Feature]: Simplify the contributing guide

Checked for duplicates

Yes - I've already checked

Alternatives considered

Yes - and alternatives don't suffice

Related problems

The current SLIM Contributing Guide is pretty lengthy and complex and it takes a while to get to the point. New contributors may find it unwieldy and not even bother.

Describe the feature request

It would be good to simply it so that new potential contributors can hit the ground running fast. Some ideas:

  • Quickstart should be a top-level section and be more bullet-pointyish
  • How to write / improve a best practice guide is currently hidden in the documentation section. Bring that to its own top-level category of ways to contribute and place that at the top
  • Provide advisement on how to contribute to SLIM in terms:
    • Need to outreach to potential other contributors as well as potential users of the solution
    • How to drag-drop and plan on the planning board what you plan to do in which quarter
  • New top-level section on "Infusion" of best practices (currently TBD but should share advice on PR strategy)
  • Note down details about the monthly tag-up of SLIM community members

[New Best Practice Guide]: Governance Best Practice Guide

Checked for duplicates

Yes - I've already checked

Describe the needs

We need a guide to satisfy process improvement needs including:

  • Triaging recommendations for changes in software
  • Software estimation recommendations
  • Closeout processes for software
  • Etc.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.