Events
Mar 17, 9 PM - Mar 21, 10 AM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Azure DevOps Services | Azure DevOps Server 2022 - Azure DevOps Server 2019
Your Git repo should have a readme file so that viewers know what your code does and how they can get started using it. Your readme should speak to the following audiences:
Write your readme in Markdown instead of plain text. Markdown makes it easy to format text, include images, and link as needed to more documentation from your readme.
Here are some great readmes that use this format and speak to all three audiences, for reference and inspiration:
Category | Requirements |
---|---|
Project access | Member of a project. |
Permissions | - View code in private projects: At least Basic access. - Clone or contribute to code in private projects: Member of the Contributors security group or corresponding permissions in the project. - Set branch or repository permissions: Manage permissions permissions for the branch or repository. - Change default branch: Edit policies permissions for the repository. - Import a repository: Member of the Project Administrators security group or Git project-level Create repository permission set to Allow. For more information, see Set Git repository permissions. |
Services | Repos enabled. |
Tools | Optional. Use az repos commands: Azure DevOps CLI. |
Note
In public projects, users with Stakeholder access have full access to Azure Repos, including viewing, cloning, and contributing to code.
Category | Requirements |
---|---|
Project access | Member of a project. |
Permissions | - View code: At least Basic access. - Clone or contribute to code: Member of the Contributors security group or corresponding permissions in the project. |
Services | Repos enabled. |
Start off your readme with a short explanation describing your project. Add a screenshot or animated GIF in your intro if your project has a user interface. If your code relies on another application or library, make sure to state those dependencies in the intro or right below it. Apps and tools that run only on specific platforms should have the supported operating system versions noted in this section of the readme.
Guide users through getting your code up and running on their own system in the next section of your readme. Stay focused on the essential steps to get started with your code. Link to the required versions of any prerequisite software so users can get to them easily. If you have complex setup steps, document those outside your readme and link to them.
Point out where to get the latest release of your code. A binary installer or instructions on using your code through packaging tools is best. If your project is a library or an interface to an API, put a code snippet showing basic usage and show sample output for the code in that snippet.
Use the next section of your readme to show developers how to build your code from a fresh clone of the repo and run any included tests. Do the following:
Remember, the developer relying on these instructions could be you after not working on a project for some time.
Provide the commands to run any test cases provided with the source code after the build is successful. Developers lean on these test cases to ensure that they don't break your code as they make changes. Good test cases also serve as samples that developers can use to build their own test cases when adding new functionality.
The last section of your readme helps users and developers to get involved in reporting problems and suggest ideas to make your code better. Users should be linked to channels where they can open up bugs, request features, or get help using your code.
Developers need to know what rules they need to follow to contribute changes, such as coding/testing guidelines and pull request requirements. If you require a contributor agreement to accept pull requests or enforce a community code of conduct, this process should be linked to or documented in this section. State what license the code is released under and link to the full text of the license.
Events
Mar 17, 9 PM - Mar 21, 10 AM
Join the meetup series to build scalable AI solutions based on real-world use cases with fellow developers and experts.
Register nowTraining
Module
Create an open-source program by using GitHub best practices - Training
Learn to create a successful open-source program by establishing contributor guidance, following proven processes, and by using community standards.
Certification
Microsoft Certified: DevOps Engineer Expert - Certifications
This certification measures your ability to accomplish the following technical tasks: Design and implement processes and communications, design and implement a source control strategy, design and implement build and release pipelines, develop a security and compliance plan, and implement an instrumentation strategy.