Solid Instruments is MIT-licensed. Your contributions must be your own work. Review the license terms and the Code of Conduct before contributing.
For questions, contact [email protected].
By contributing to Solid Instruments you assert and agree that:
- Your contribution is your own original work.
- You have the right to assign the copyright for the work (it is not owned by your employer, or you have been granted copyright assignment rights in writing).
- Your contribution is licensed under the terms applied to the Solid Instruments project.
Contents of the repository are organized as follows.
/cicdhouses source objects which define the behavior of the CI/CD pipeline/doccontains content and configuration files that serve as the source for the project website./examplecontains sample projects that utilize the product libraries./srchouses the source for the product libraries./testhouses the test projects for the product libraries.
Solid Instruments is developed using Visual Studio with the following extensions installed.
- CodeMaid is used to maintain standard document formatting throughout the project.
- Visual Studio Spell Checker is used to uncover spelling errors.
CI/CD tooling is managed and defined by cicd/modules/AutomationTools.psm1. The build environment setup process (initiated by cicd/scripts/ResetEnvironment.ps1) installs the following tools.
- The .NET SDK is the project's foundational build and test instrument.
- codecov.exe publishes test coverage reports.
- DocFx produces the project website.
- HTMLMinifier minifies the project website.
- OpenCover executes the project tests and produces test coverage reports.
- powershell-yaml extracts configuration information during the build process.
- psake organizes and groups CI/CD operations (see
psakefile.ps1).
The Solid Instruments team adheres to a variety of design and workflow conventions, which are described here. We value consistency in these practices. Please feel free to contact us with questions using any available avenue.
New contributors should familiarize themselves with basic architectural conventions by reviewing the Architectural Guide. The existing body of source can often be used as a reliable authority when making design decisions but, when in doubt, ask for advice from experienced contributors or contact [email protected].
The .editorconfig and CodeMaid.config files, in combination, define most of the project's styling guidelines. More information can be found by reading the Development Guidelines. When in doubt, look to examples within the source for styling guidance, or contact [email protected] with questions.
The Solid Instruments team uses RapidField Revision Control Workflow 1.1, a GitFlow-like strategy for managing source branches.
The following patterns define the project's branch naming and usage conventions. Five-digit numeric tokens ("00000") represent an associated issue number.
master is the root branch and represents, at all times, the state of the latest production release. The team aims to maintain a 99.9% minimum build success rate for master.
Branches matching the pattern hotfix/00000-{semantic-key} are children of master and house active work associated with an urgent production defect. Pull requests to hotfix branches may be used to share unfinished work with other team members working on associated issues, but those pull requests should pass all status checks.
Branches matching the pattern release/v0.0.0 are children of master and house completed, tested and integrated work for a named release. Release branches should always be in a releasable state.
develop is a child of master and serves as an integration branch for completed and tested work sourced from defect, feature and maintenance branches. The team aims to maintain a 99.9% minimum build success rate for develop.
Branches matching the pattern defect/00000-{semantic-key} are children of develop and house active work associated with a non-urgent defect. Pull requests to defect branches may be used to share unfinished work with other team members working on associated issues, but those pull requests should pass all status checks.
Branches matching the pattern feature/00000-{semantic-key} are children of develop and house active feature development work. Pull requests to feature branches may be used to share unfinished work with other team members working on associated issues, but those pull requests should pass all status checks.
Branches matching the pattern maintenance/00000-{semantic-key} are children of develop and house active project maintenance work. Pull requests to maintenance branches may be used to share unfinished work with other team members working on associated issues, but those pull requests should pass all status checks.
Branches matching the pattern user/{username}/00000-{semantic-key} serve as source branches for pull requests targeting defect, feature and maintenance branches. User branches may contain work-in-progress and there are no requirements for them with respect to status checks.
RapidField Revision Control Workflow 1.1 diverges from GitFlow by introducing defect and maintenance branches, which are treated like feature branches from a process perspective but are used for different purposes. The workflow is diagrammed below.
Solid Instruments releases are versioned using the Semantic Versioning 2.0.0 specification. Release versioning is controlled via appveyor.yml. Please do not submit pull requests that modify the build version. The maintainers manage release versioning.
Ready to start contributing? You know what to do.
git clone https://github.com/RapidField/solid-instruments.gitAfter cloning the repository, navigate to the root directory in an administrative PowerShell session and execute Build.ps1 to install the command-line tools and verify the status of your build.
.\build.ps1 -interactiveDuring development it is good practice to ensure that your build remains in a passing state. Before pushing commits upstream, open a PowerShell console and execute the verify task in the project root.
psake verifyFirst-time contributors are welcome to start with any open, unassigned issues labeled Tag-GoodFirstIssue. After picking one, leave a comment on the issue so that we can assign it to you and promote its status.
Revision control plans are provided with the descriptions of all accepted issues. Please review carefully before starting.
If you encounter problems or if questions arise, there are several options available for finding help.
- Check out the API Reference.
- Ask the community for help via Gitter.
- Open a new issue.
- Email the core team at [email protected].
