-
Notifications
You must be signed in to change notification settings - Fork 13
Home
So you want to help and are looking for a simple guide? You've come to the right place. We hope this documentation serves as a good first step!
First, you may want to familiarize yourself with the TIP initiative and the group working on the technical aspects of it. The documentation is conveniently located here. And the charter is located here.
The next step will likely be some basic tooling and some pointers on how all of this works, in case you don't already know. Don't worry if the information becomes a little confusing. There are a number of people from the group who can help orient you and there are checks to prevent accidents from adversely affecting the code-base, so don't be scared.
Microsoft Visual Studio Code is an excellent text editor is all you need to alter the code in this repository, but if you want syntax highlighting and additions that make life a little easier, you may want to use an actual editor like this free tool we recommend--Visual Studio Code.
VS Code YAML extension is the VS Code extension that will give you the syntax highlighting for YAML. Syntax highlighting changes the color of the words in a document to indicate its syntactic function.
VS Code Open API (Swagger) Editor is the extension that will allow you to navigate the OAS document more easily and verify that the code is written correctly.
SourceTree is a Git GUI that can make interacting with Git a little bit easier if the command line interface (CLI) of Git is intimidating. There are a number of Git GUIs out there, and VS Code even has extensions that make life easier all in the same tool. Some are better than others when it comes to features and ease of use and this recommendation is a good start.
-
An exhaustive list of code generating tools. These tools can create stub code to ramp-up development against TIP specifications. Below are a couple of vendor favorites.
-
NSwag · NSwag is a Swagger/OpenAPI 2.0 and 3.0 toolchain for .NET, .NET Core, Web API, ASP.NET Core, TypeScript (jQuery, AngularJS, Angular 2+, Aurelia, KnockoutJS and more) and other platforms, written in C#.
-
openapi-generator · Code generation for server stubs and client SDKs. It also provides a command line utility for validating OpenAPI syntax (openapi-generator validate). Circleci is currently running openapi-generator validate on all incoming Pull Requests, you can run these same tests locally before pushing changes.
Here are a list of documents you may want to familiarize yourself with in order of importance when contributing to this repo.
TIP Initiative Google Doc details the properties that are or will be included in this code base.
Git Flow gives you and introduction in how Git specifically works and how version control systems (VCS) work in general.
Open API Specifications 3.0 is the structure the TIP initiative follows when creating TIP API specifications.
API style follows the Microsoft API developer guidelines with a lot of the much easier to read Python Style Guide sprinkled in for good measure.
- Use lowerCamelCase for all elements. These appear in all of the API endpoints and schemas. For single value elements, this MUST be a singular word (as opposed to pluralized - that means no "s" on the end). Array elements MUST be pluralized.
- Use CapWords for element type definitions. These appear in the schema definitions regularly (especially Common Models) to define an object's structure. They should be singular (as opposed to pluralized) words. We use the CapWords style because it's very easy at a glance to see if you're defining an object or using it.