May be a well known question, but actually I'm asking this, because I'm not familiar with these tags.
I've seen similar types of tags in various Github projects, especially in their README.md. My questions are manifold regarding these:
What's the purpose of these tags?
How to generate them?
Is there any good practice or documentation that suggests what types of tags can be used or should be used in a project?
When a project can be determined viable using such a tag?
What's the purpose of these tags?
These images are provided by external services, often continuous integration services, and are used to show interesting information about the repository.
For example, the first badge you show in your example says that the build is "passing" (the exact definition of this will be build-specific, but it commonly means that the tests pass and nothing blew up during the most recent build).
The third example, coverage: 12%, is a code coverage report.
How to generate them?
Each service will have its own way.
The second badge in your example is from Scrutinizer, and unfortunately I can't find documentation about its badges. But most badging systems work by giving you a link for each project or job that you can use on your website or GitHub or whatever, and when a build happens the badge's appearance is updated accordingly.
The Travis CI documentation contains a good example.
Having answered the first to questions, I think your last two largely disappear. The badges that can be used are determined by whatever services you can find. The badges that should be used are entirely up to you.
Related
I have it in my head to help people at my company get better by finding a way to highlight and call out good code.
In particular, I'd like to be able to mark a file (not a repository or directory) as having a "gold star" (or another badge) so people browsing our source code who see the badge can see they're looking at a really good implementation they might take inspiration from.
I'm taking inspiration from the code owners feature on GitHub where there's a little padlock icon on a file if it's assigned ownership by the CODEOWNERS file.
Is it possible to do a custom "badge" on GitHub? If so, what's the API?
Browsing the GitHub documentation and searching online, I wasn't able to find anything explaining how to do something like this. Most folks were talking about the little images badges like the code coverage badges people put in their readme files.
Checkout this thread. You can submit feature request to GitLab and GitHub or in case of GitLab code your own feature and submit PR.
Here are some closely related discussions. Probably you have already seen them and are not looking for them but you might use them to get idea of how to create the feature that you want.
The Shields service (at shields.io) provides a way to create custom badges for your projects. These are badges are very common and are frequently used to show status information about the project, or demonstrate tools that were used for the development of your project. (...more)
Also checkout Bring Your Own Badge
When creating a GitHub Pull Request, it is often that a file (script, lib, etc.) may be completely replaced (or introduced) with one from another repo. Sometimes, the file requires small changes. I'm trying to establish a standard for my team for how to communicate where the file came from and what changed. In the same way that you can craft a URL to highlight a specific change in a single repo, I'd like to be able to highlight a change across repos.
The reality may very well be that GitHub does not offer this. (I do a lot of research before asking questions. Consequently, the answer is often, "you couldn't find an answer because it is impossible.") In which case an alternative will be needed. One possibility might be to generate a diff in markdown and add it as a comment. (Notice I improved that answer back in 2016.)
One possibility might be to generate a diff in markdown and add it as a comment.
Good idea.
One alternative which would not depend on a PR comment would be to use git notes. They are not supported/displayed by GitHub since 2014 and they are criticised, but they would remain in your case possible way to leave... well a note describing where some of the PR files are coming from.
I guess those something related to project deployment tools. Actually what are those, how to add those and what is the benefit of those?
Edit 1
Is there any billing issue(payment) with those or those are free?
They're known as Code Repository Badges, and detail various aspects of the general stability of the repository. There are a number of badges available, but the most common are:
build: passing: Indicates that the project's tests are all passing. This is usually set up through Travis-CI integration.
coverage: How much of the project is tested. 75% of the code in your image has been through passing unit tests.
dependenices: How many dependencies the repository has on other repositories in order to run
devDependencies: How many dependencies the repository has on other repositories in order to develop
These are something known as Code Repository Badges.
To quote an online resource:
As people who are passionate about writing great code we display "badges" in our code repositories to signal to fellow developers that we set ourselves high standards for the code we write, think of them as the software-equivalent of the brand on your jeans or other reliable product.
In short, it's a way to say that "hey, look, my GitHub project has a high standard!". The link above actually goes into a fair bit of detail on the different badges, but let me just point out two common ones shown in your picture:
"Build passing"
This makes use of continuous integration tools like Travis CI which will help to build and test your code when you push code onto a GitHub repository (given that you have set up Travis CI for that repository).
Using this can ensure that no breaking changes get merged into your project, and also prevents wasting reviewers' time and effort on pull requests that are not "working".
"Coverage"
This measures how much code in your GitHub project is actually tested. It makes use of tools like Codecov, again premised on the fact that you have set up such tools for your repository.
Using this can remind contributors to write proper tests for the code, so that any potential bugs in the code can be detected.
As you can see, the badges help to ensure that your project maintains a certain standard, which can improve your project quality, and even attract people to work on your project (e.g. in the case of open-source software hosted on GitHub).
What are they
These are "badges". Badges are offered by all kinds of build tools, package managers and so on.
Say you're using AppVeyor to do your continuous integration and deployments, in your project settings in AppVeyor they provide a HTML / markdown snippet for you to embed in places like GitHub to show everyone looking at your GitHub readme that the last build was successful.
Badges are typically (but not always) dynamic in the sense that the service provider (npm, AppVeyor, etc) will serve the badge from a URL (in the code snippet you get) and when a client grabs that image it will show the latest state of the badge's data (build succeeded/failed, available on npm, tests failing, code coverage %, etc.).
How to use them
You get the snippet of code from the service provider (npm, AppVeyor, etc) and just paste it straight into your readme or wherever you like.
What's the benefit
This varies obviously depending on what the badge is showing, but some examples would be:
Build status badge: Tells you whether or not the latest code in the current branch can be built. Useful for quickly showing people there's WIP or issues with the codebase.
Code coverage badge: Tells you the % of code covered by unit tests. Useful if you came across a GitHub repo and wanted to know the quality of the code base and unit test coverage if that is important to you.
Tests passing badge: How many tests are passing/failing. Similar to build failed status gives you a quick red light as a potential consumer of this library, or even as a dev on the team that Houston, we have a problem.
NPM badges: Version badges, available, download count, etc. are all useful info indicators to people.
Misc. static badges: Some services/libraries offer badges that are just static and usually for promotional purposes of their library/brand/service. Framework X might create a badge with their logo/name and developers who like it can say that their website/framework depends on/uses Framework X by putting that badge in their own readme.
The possibilies are endless.
What are the main functionality differences between Github Wiki and Readme,
Asking those that have used both readme and wikis extensively. So that we can better decide which to use for the purpose of outputing verbal information. This would be based on your answer. Thanks.
As examples, some have used wikis --
http://github.com/mbostock/d3/wiki
http://github.com/ParticleCore/Particle/wiki/Features
and some people have used readmes --
http://gist.github.com/atcuno/3425484ac5cce5298932
no better place to ask? -- meta.stackexchange.com/questions/157888/what-site-is-good-for-github-questions
Talking about a project repository :
Readme.md is the packaging
wiki pages is made for development/contributors documentation
gh-pages branch hosts user documentation
Both readme & wiki have no function, except for providing information. Github recommends you to create a README.md to display a short summary & usage of your repository, while the Wiki is totally optional.
I have to cross this bridge today, and in addition to this helpful thread I also found reading up the following helpful
https://docs.github.com/en/communities/documenting-your-project-with-wikis/about-wikis
https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes
A key excerpt from there that I found useful and to the point
A README should contain only the necessary information for developers to get started using and contributing to your project. Longer documentation is best suited for wikis.
Based on those and the other answers here, it makes sense to be high level in the readme along with all the getting started information (i.e. local setup), and leave the long form information such as application features, design principles, etc. in the wiki.
Another major difference of course is that the readme will get versioned whereas the wiki will not. Versioning of this doc is not a major concern for us, but it could be for you!
Almost every issue needs a documentation subtask.
Many issues need a localization subtask.
Should documentation and localization issues have their own workflow (by issue type)?
Should each project have documentation and localization components, so that those issues would be automatically assigned to the component owner?
Should "Create Issue" screen have a checkbox "Needs documentation", which would create a documentation subtask with specific fields?
I agree, only create issues or subissues for work that occurs in parallel and needs a different assignee or due date or such. If the work happens in every case then build it into the workflow instead.
The other thing to be aware of is that whatever is entered in a field such as "Notes for Documentation" always needs human review before being sent to a customer.
I have a different understanding for working with JIRA. For me, JIRA helps me understand when I have to do something, what the status is, and when I'm done with it. When documentation and localization is every time necessary, I would not like to overflow my JIRA with all these sub-tasks everyone understands that they are necessary.
The only reasons, why these should be extracted as sub-tasks (and managed with a workflow) are:
You have normally a different assignee for documentation and / or localization, so you are able to assign that to a different person.
Their workflow is different, therefore you want to manage it separately.
I would not expect additional components for them, because when you want to isolate them, just have a custom field for it (or create a sub-task like work item for documentation and localization, don't know if that is easily possible).
I would not add that "Needs documentation" flag, because people that add issues often don't know if documentation is necessary. So no, I would not add them as sub-tasks, neither as additional flag, but explain everyone that documentation and localization is necessary. There should be ways to check that automatically, without any issue ...
And of course, you are free to add a documentation screen with additional custom fields. There you could document in implementing the issue what you have done about documentation and internationalization. So checking that these are empty, would replace the flag you have mentioned.