docs: Add contributing guidelines #8222
Conversation
Bad3r
requested review from
andelf,
cnrpman,
logseq-cldwalker,
RCmerci,
sawhney17,
sprocketc,
tiensonqin and
xyhp915
|
@logseq-cldwalker when you get a chance, I would appreciate any feedback on this PR. |
|
@Bad3r I can take a look tomorrow. Fyi the core team uses https://github.com/logseq/logseq/pulls?q=is%3Apr+is%3Aopen+-label%3A%3Atype%2Fhold+draft%3Afalse+NOT+WIP+in%3Atitle for looking for PRs that are ready for review. I assumed this wasn't ready b/c of the "WIP" |
Bad3r
changed the title
Bad3r
added
the
:type/dev
|
Oh good to know! |
Bad3r
force-pushed
the
docs/add-CONTRIBUTING.md
branch
from
97be796
to
f0b9164
Compare
There was a problem hiding this comment.
@Bad3r Thanks for nudging us to get a first version of this out. I finally got around to reviewing this as most of the team will be back soon. I've left some small feedback and left one open question for the team
CONTRIBUTING.md
Outdated
| ``` | ||
|
|
||
|
|
||
| ## <a name="rules"></a> Coding Rules |
There was a problem hiding this comment.
This is what we are striving towards but I don't think we consistently enforce this level of testing or documentation. I can just rewrite this section after this PR
There was a problem hiding this comment.
@logseq-cldwalker I guess the question is; should this describe how it's done now or use this as an opportunity to write what we want to transition to in the near future.
Could you give me a bit more insight into what you have in mind for this section? . Also, would you mind making the changes before merging this PR? It would be great to make sure we're on the same page.
There was a problem hiding this comment.
It'd take longer to explain than to just do it. I'll rewrite this at the end of this PR as this something for engineers to fill in
CONTRIBUTING.md
Outdated
| - **Note:** Because the developers need to copy and paste the code snippet, including a code snippet as a media file (i.e. .gif) is not sufficient. | ||
| - Errors from the Dev Tools Console (open from the menu: View > Toggle Developer Tools or press CTRL + Shift + i) | ||
|
|
||
| You can file new issues by selecting from our [new issue templates][new-issue] and filling out the issue template. |
There was a problem hiding this comment.
Optional: It could be nice to just point to the template link and then use this section to elaborate on things that aren't in the templates like the Dev Tools Console or tools in the new bug report page
There was a problem hiding this comment.
@logseq-cldwalker don't you think that's a better fit for the docs folder?
I do think such section will add value; We can also link to it from the issue template.
The only reason I am hesitant to include it in this document is that it will be long and will require screenshots etc..
Don't think we have a corporate CLA but if we plan on doing it later @andelf would know |
CONTRIBUTING.md
Outdated
|
|
||
| ## <a name="question"></a> Got a Question or a Problem? | ||
|
|
||
| Do not open issues for general support questions or feature requests as we want to keep GitHub issues for bug reports. |
There was a problem hiding this comment.
I'm not sure our process, but I feel like something should be said about GitHub discussions here.
There was a problem hiding this comment.
@bendyorke honestly I am trying to get GitHub Discussions shutdown. I do not think its a good idea to have it. We should consolidate it to the Logseq forum.
@logseq-cldwalker curious if you have any thoughts on this.
There was a problem hiding this comment.
There was a problem hiding this comment.
@cnrpman any thoughts on closing GitHub discussions and consolidating it into the Logseq forum?
|
@Bad3r Feel free to address comments soon. I've asked the team internally to look at this so if we don't hear from anyone else, would be great to finish the PR this week |
|
@Bad3r Would be great to address feedback as most of the feedback is minor and would like to clean up the review queue. I can finish it up if it's still hanging out |
Sounds good, will get it done in the next 24 hours. |
|
Addressed the feedback thus far and added instructions on naming PRs instead of commits. |
Bad3r
requested review from
alxlg,
ens100,
hdansou,
benjypng,
logseqramses,
sawhney17 and
situ2001
| - Images, animations, or a link to a video showing the issue occurring | ||
| - A code snippet that demonstrates the issue or a link to a code repository the developers can easily pull down to recreate the issue locally | ||
| - **Note:** Because the developers need to copy and paste the code snippet, including a code snippet as a media file (i.e. .gif) is not sufficient. | ||
| - Errors from the Dev Tools Console (open from the menu: View > Toggle Developer Tools or press CTRL + Shift + i) |
There was a problem hiding this comment.
Optional: This link may be helpful, as @cnrpman usually uses it to guide people that have issues.
https://help.figma.com/hc/en-us/articles/360041949073-Use-Chrome-Developer-Tools
There was a problem hiding this comment.
That's a good guide. This is what @logseq-cldwalker was asking about.
Optional: It could be nice to just point to the template link and then use this section to elaborate on things that aren't in the templates like the Dev Tools Console or tools in the new bug report page
I do not link to external 3rd parties. I prefer that links are either from Logseq.com or GitHub.com.
It's best we can create our own document with instructions on using Dev tools and other tools that can be helpful in diagnosing issues.
For example; we can add a section on diagnosing performance issues, etc..
We can use this guide as the base for ours.
Bad3r
force-pushed
the
docs/add-CONTRIBUTING.md
branch
from
cd77272
to
850d80b
Compare
Bad3r
force-pushed
the
docs/add-CONTRIBUTING.md
branch
from
850d80b
to
75d8659
Compare
Bad3r
force-pushed
the
docs/add-CONTRIBUTING.md
branch
from
75d8659
to
f931413
Compare
|
@logseq-cldwalker any notes on the changes? |
|
Sorry I didn't get to this. Aim to get to this on Monday |
Also tweaked some wording and added emojis of course
There was a problem hiding this comment.
@Bad3r Thanks for kicking off a great contributing doc! 👍 🎉 I've added some emojis, rewritten the PR section and added a how to help section
CONTRIBUTING.md
Outdated
|
|
||
| You can file new issues by selecting from our [new issue templates][new-issue] and filling out the issue template. | ||
|
|
||
| ### <a name="submit-pr"></a> Pull Requests (PR) |
There was a problem hiding this comment.
In re-reading this section, we don't follow most of these PR conventions. I've rewritten this section to have the focus be on the PR submission and the conventions that are actively used
logseq-cldwalker
force-pushed
the
docs/add-CONTRIBUTING.md
branch
from
3429161
to
7b36ee3
Compare
* docs: Add contributing guidelines * Add a how to help section and redo PR section Also tweaked some wording and added emojis of course * Fix up sub lists --------- Co-authored-by: situ2001 <yongcong2001@outlook.com> Co-authored-by: Gabriel Horner <gabriel@logseq.com>
* docs: Add contributing guidelines * Add a how to help section and redo PR section Also tweaked some wording and added emojis of course * Fix up sub lists --------- Co-authored-by: situ2001 <yongcong2001@outlook.com> Co-authored-by: Gabriel Horner <gabriel@logseq.com>
Adding a contributing guidelines to Logseq.
These guidelines are based on and inspired by the Angular and VS Code projects contributing guidelines.
Questions for Logseq team:
This PR should remain open until these questions are answered, and the document is updated. Preferably, all Logseq team members should review this document.
In the future, we might want to consider making the document shorter and utilize GitHub wiki for all dev related live documents