This my first time trying to contribute to open source projects. I'm wondering what it means when there is a "pleaseverify" label. Does that mean the team wants someone with experience to verify the bug first before someone else works on it? Or does it mean that I, as a new contributor, have to verify that the bug exist before working on it?
PS. I have googled but cannot find information on the topic.
First, creating a label on GitHub is not linked to some naming convention: you can use any name you want.
Each project has its own convention.
Here, for instance:
I've added the pleaseverify tag just so that we can track or ask for more input from other developers/users that are having the same problem.
Related
first question so please don't treat me too harshly (going mad here)
I am trying to convert one string to another, for all .md files for a github-pages hosted repository.
[[this]] -> [this](this)
It feels like something trivial, but to be honest I don't even know where to start.
I basically want to have apply a kind of "find and replace" function for every .md file for every instance of a [[x]] in it.
I tried looking at every documentation
But either I am unable to understand it, or seems that it is impossible on git-hub pages.
Liquid is no help afaik (because you need to explicitly provide an input? I can't define a general conversion for the whole page, right?)
Afaik I can't edit jekyll plugins on github pages without local hosting, and none of the whitelisted plugins seem to help.
If it's indeed impossible:
Then I will have to go locally host Jekyll. In that case, I would love any tips on how it could be possible. For example by creating custom plugins.
I really would love your help - thank you in advance!
I want to give the users of my repository some info on how they should report issues and what info they should provide. What is the best way to present this information, and where? I was hoping there would be a readme on the /issues tab but there seems no such option. Maybe I should create an 'issue' named 'Read before creating issue'?
If you're worried about the added clutter in the root directory of your project.
You can put CONTRIBUTING.md, ISSUE_TEMPLATE.md, and PULL_REQUEST_TEMPLATE.md files in the project directory.
Yes, it will easy both parties to creating the issue or pull request fill all info.
What is the best way to present this information, and where?
Put it into your this three files and file name should be same as here.
More information about it
I'm not sure if github exclusively provides any such feature. Alternatively, you could include the guidelines (or link to- how to create an issue) in the readme.md file at the main branch of the project (e.g. a section #HowToCreateAnIssue along with other sections). At least, this is what I follow.
For my Projects (and I guess thats how most People will handle it) I added a readme to the Projects repository and create a link to the most important wiki pages. The wiki will be managed as an additional repository and provides possibility to store Information and updates as needed.
If you also have a Webpage created this could also be a place to add some Information on how to participate as a contributor.
I posted a new issue on github for an opensource project. Shortly after posting I got a comment on the new issue saying "ya I agree and also [XYZ subject tangentially related to your ABC issue] needs to be fixed also".
On Stackexchange websites there is clear documentation specifying one topic per question: https://meta.stackexchange.com/questions/39223/one-post-with-multiple-questions-or-multiple-posts (maybe there is a better link but this is the link I found).
Where on github.com can I find something similarly authoritative to point a user to that says "it is recommended to post one topic per Github-issue"?
There isn't, and it doesn't make sense for GitHub.
Every person who owns a repo on GitHub can decide for himself how he manages the issues in his repo. Usually, you find such information somewhere in the repo. Sometimes a repo has a CONTRIBUTING.md file that details this. If it has, then it is linked when you try to open an issue. If it hasn't, look for this info in README files or in the wiki or the projects homepage.
But sometimes, you will not find it. And by that time, you start using common sense. Usually, the rule is to only discuss one issue per opened issue because that makes sense from a software development point of view. Its the only way you can label things properly, mark then done as properly, assign them to a person properly. And most importantly, it means that all info related to one issue is found at one place, making it easy to find at one glance.
Thus, virtually every contribution guidelines will state something in that direction, and when you can not find those explicitly, the general consensus and the expectancy is what I just laid out above.
Does the wiki that installs with a GitHub repo support directories? Our wiki is cluttered with pages, and we are looking for a way to organize them better.
We tried pulling the repo, creating local directories, and moving things around, but when committed back, the wiki didn't pick up the changes.
I was having the exact same issue and tried variants of what you tried. Nothing stuck. Asked GitHub support about it and received a reply that essentially said "No, but we'll let the developers know that people are interested in this feature."
So the short answer is "No", and the long answer is "No, but maybe in the future."
Actually, it looks like github added support for directories recently.
I was able to do the following:
Move an existing markdown file to a new directory.
Create a new markdown file in an existing directory (created in the former step).
Create a new markdown file in a new directory.
In all cases, the existing pages were still there and new pages were added.
The one constraint that remains is that your file names must be unique. If you have more than one file with the same name, only one of them will show up in the wiki (I'm not sure which.. ).
The GitHub wiki (aka Gollum) does use directories but not in the way you may expect.
The documentation on the Gollum wiki could use some work but this is what I have figured out mostly via testing.
All files appear in the root of the wiki no matter where they are placed in the repo.
_Header, _Footer and _Sidebar files are per-directory, but inherited if there is
none present in a child folder.
File links can be relative to the source file (keep your files with your content).
So, if you want directories for namespacing you are out of luck. Consider using the {namespace}-{page} scheme for namespacing.
It's not the an ideal solution but the workaround would be to create a custom sidebar where you create a table of contents with links to your pages. I find this to be better than folders anyway because it allows you to have a link to a single page under multiple hierarchies.
Actually, there is still a limitation. Yes, you can add 1 level (so, 1 subfolder). But that's it! I refactored my whole documentation layout, creating multiple levels of subfolders for organisation, but that was a no-go.
sigh
I must say: I'm appalled by this Gollum thing. I'm surprised Github even picked it up.
Well, that's a disappointing missing feature!
What I try to do is to actually have directories under a docs directory and in each one, a README.md file.
Not great...but works for documentation and organizes stuff.
If you want to go further, you can have a different branch only with these files.
Still no intention of adding this 9/2022.
https://github.com/orgs/community/discussions/23914
What template do you use for comments on code commit?
One example of a template is:
(change 1): (source file 1.1, 1.2): (details of change made), (why)
(change 2): (source file 2.1): (details of change made), (why)
Ideally each change should be mapped to an issue in the issue tracker. Is this template alright?
Here are my thoughts... all these will be open to interpretation depending on your particular development methodologies.
You should be committing fairly often, with a single focus for every commit, so based on that, comments should be short and detail what the focus of the commit was.
I'm a fan of posting the what in your comment, with the why and the how being detailed elsewhere (ideally in your bug tracking). The why should be the ticket, and upon closing the ticket, you should have some kind of note about how that particular issue was addressed.
A reference to your bug tracking system is good if it isn't handled otherwise (TRAC/SVN interaction, for example). The reason for this is to point other developers in the right direction if they're looking for more information on the commit.
Don't include specific file names unless the fix really complex and detail is needed. Even still, complex details probably belong in bug tracking with your implementation notes, not in version control. Files edited, diff details, etc, should hopefully be included with version control, and we don't want to spend time duplicating this.
Given these ideas, an example commit comment for me would be something like
Req3845: Updated validation to use the new RegEx validation developed in Req3831.
Short, communicates what was changed, and provides some kind of reference for others to get more info without hunting you down.
I prefix each paragraph with + - * or !
+ means its a new feature
- means feature is removed
* means feature is changed
! means bugfix
I don't think you should commit detailed description about what parts of the code are changed, because that's why every VC has diff :)
If you use a bug tracking system, include relevant ticket numbers.
You do not need to mention changed files, or your name. The source repository can figure that out by itself. Describing the changes also only makes sense if it is not non-trivially obvious from the diff.
Make sure you have a good first line, because this frequently appears in the change history view, and people need to find things by this (the bug tracking ticket number should go there, for example).
Try to commit related changes in a single changeset (and split unrelated changes into two commits, even if to the same file).
I try to follow the same rule as for code comments:
Explain the WHY, not the HOW.
IMO a comment should contain a reference to the issue (task tracker, or requirement). Which files are affected is already available from the version control system. Apart from that, it should be as short as possible, but still readable.
I try to keep my fixes in separate check-ins.
I don't use an actual template, but a mental one, and it's like this.
Issue - dev level summary of
issue.
The issue tracker has all the management details, and the changes/diffs can be reviewed for code changes, so the comment is for dev's to understand the why/what of the issue.
Here's what I've seen used successfully:
Reference to bug number or feature ID
Brief description of the change. What was changed.
Code reviewer (to ensure you have one) unless handled by the checkin system.
Name of tester or description of which tests were run (if late in the process and you are being extra careful)
I use the simple technique described by Chaosben on the JEDI Windows API blog.
In order to get a fast view on the
changes made to a repository, we
suggest to write brief concise
comments starting each line with one
of these chars:
+ if you added a feature/function/…
- if you removed a feature/function/bug/…
# if you changed something
Doing it this way, other developers may find the desired revision much better.
First, commits should solve one single problem (separate commits for logically separate changes). If you don't know what to write in the commit message, or the comit message is too long it might mean that you have multiple independent changes in your commit, and you should split it into smaller items.
I think that commit message conventions expected and used by git makes much sense:
The first line of commit message should be a short description
If appropriate, prefix mentioned above summary line with subsystem prefix, e.g. "docs:" or "contrib:"
In next paragraph or paragraphs describe the change, explaining why's and how's
Keep in mind that if someone needs details of what changed, they can get a diff. That said, I just usually write a sentence or two for each major change, and then lump any minor fixes at the end.
There is no hard and fast rule as its plain english. I try to explain the work done in minimum words possible. Anybody looking for history of changes just want to know what happened in a particular change. If anybody is after more details then its there in the code.
Second thing I follow is if there is any bug associated then stick that in or if its related to any dev task then associate that with the change.
If two files were changed for different reasons, they should be in different commits The only time you should commit more than one code file at a time is because they all belong to the same fix/change