E.1 Collaboration#

[1] Overview#

There are several ways to collaborate on writing and improving rivt docs, and to contribute to improvements of rivtlib and rivt frameworks.

1. Upload public rivt files to GitHub and Google Drive

Public rivt files may be collaboratively improved by:

  • forking to create different or improved versions of rivt files.

  • providing pull requests.

  • submitting issues and bugs.

Public rivt files are generated by rivtlib through a setting on each rivt file section. The files are stored in the _rivt-public folder which may be uploaded to a public GitHub repository. rivt also publishes the formatted text form of the rivt doc or report to a README.txt file. When the _rivt-public folder is uploaded to a repository, the README is displayed on the landing page and can be searched across all GitHub using a search interface.

rivt public folder structure

[rivt-]Report-Label/          rivt Folder
    ├── .vscode/                    optional VSCode settings
    ├── README.txt                  rivt-generated report
    ├── [_rivt-public]/                 public subset of rivt files
        ├── rvsrc/
        ├── README.txt
        ├── rv-101-filename1.py
        ├── rv-102-filename2.py
        ├── rv-201-filename3.py
        ...

2. Contribute to rivt and rivtlib

rivtlib can be improved by:

  • providing pull requests.

  • submitting issues and bugs.

  • contributing to documentation and examples.

rivt can be improved by:

  • contributing to packages and extensions used by rivt.

Packages and extensions are summarized here and here.

3. Contribute to rivt frameworks

As a Python file, rivt can work efficiently with a large variety of programs using scripts and shell commands. Frameworks are collections of programs and scripts that facilitate the use of rivt with other programs. The basic and extended frameworks are described here.

The generality of rivt allows for the developement of domain-specific frameworks that include programs and scripts for that domain. For example, a rivt structural engineering framework could include scripts for running, pre- and post-processing:

4. Real-time Collaboration

Within an IDE or cloud environment, rivt files can be collaboratively developed and edited.

Examples include:

Visual Studio Live Share.

and

CodeSpaces

[2] Public GitHub files#

A feature of rivt is fine-grained control over public sharing of all or parts of a rivt file. Public rivt files are generated by rivtlib on a section by section basis defined by the API header substring. Each API function defines a section and has a public/private setting in the header. Sections are private by default (see :doc: <rvF01-quickref>).

rv._("""Section Label | doc;stored, private;public, section;merge

     Content substring indented 4 spaces

    ...

    """)

Sections are written to a rivt file in the /public folder with a file name composed as:

rivt file name

    rvAnn-filename.py

modified with an additional hyphen

    rv-Ann-filename.py

The public folder may be uploaded to a GitHub repo for public sharing. When files are downloaded for reuse the extra hyphens may be removed with a batch remove command (e.g. in VSCode).

[3] Public Google Drive files#

For each rivt file that is published a corresponding public rivt file is written to the public folder. The default contents of the file are the API rivt string headers. If the header parameter public is included in the header, the rivt string content is also written to the public rivt file.

The public folder can be uploaded to a public repository and updated with Git as the project develops.

The web site OpenModels.info is a Google Drive repository of open source engineernig model files, including rivt files and reports.

[4] Git and GitHub#

GitHUb is a popular and widely used cloud and version control system based on the Git program that may be downloaded here.

Git and GitHub are part of the rivt framework. Git is a free, open-source, distributed version control system designed to manage and track changes in files. It allows multiple people to work on the same project simultaneously without overwriting each other’s work. GitHub is a web-based platform for hosting, managing, and collaborating on code built around Git. It allows teams to work together efficiently on software projects and provides features like pull requests, issue tracking, and project management.

Each rivt project is typically stored in its own repository. Every user of GitHub has a personal account with essentially unlimited repositories.Free accounts provide for:

  • Unlimited Repositories: You can create as many public and private repositories as you need.

  • Unlimited Collaborators: There is no limit to the number of people you can work with on your repositories.

  • Community Support: You have access to the GitHub Community Discussions for help.

  • Core Services with Usage Limits: The free plan includes a certain amount of monthly usage for services:

    • GitHub Actions: 2,000 minutes per month for private repositories

      (unlimited for public repositories).

    • GitHub Codespaces: 120 core hours and 15 GB of storage per month.