CONTRIBUTING.org, Fix typos, etc.
This commit is contained in:
parent
4dc1d7640a
commit
291cf9d671
|
@ -4,7 +4,8 @@ Spacemacs is a volunteer effort. We encourage you to pitch in. The community
|
||||||
makes Spacemacs what it is. We have a few guidelines, which we ask all
|
makes Spacemacs what it is. We have a few guidelines, which we ask all
|
||||||
contributors to follow.
|
contributors to follow.
|
||||||
|
|
||||||
You can only consider reading the sections relevant to what you are going to do or just watch this video [[https://www.youtube.com/watch?v=OMS-3Jl05mE&feature=youtu.be&list=PLpr9V-R8ZxiCHMl2_dn1Fovcd34Oz45sua][here]]:
|
You can only consider reading the sections relevant to what you are going to do
|
||||||
|
or just watch this video [[https://www.youtube.com/watch?v=OMS-3Jl05mE&feature=youtu.be&list=PLpr9V-R8ZxiCHMl2_dn1Fovcd34Oz45sua][here]]:
|
||||||
- [[#asking-for-help][Asking for help]] if you are about to open an issue to ask a question.
|
- [[#asking-for-help][Asking for help]] if you are about to open an issue to ask a question.
|
||||||
- [[#reporting-issues][Reporting issues]] if you are about to open a new issue.
|
- [[#reporting-issues][Reporting issues]] if you are about to open a new issue.
|
||||||
- [[#contributing-code][Contributing code]] if you are about to send a PR.
|
- [[#contributing-code][Contributing code]] if you are about to send a PR.
|
||||||
|
@ -67,8 +68,8 @@ Issues have to be reported on our [[https://github.com/syl20bnr/spacemacs/issues
|
||||||
step guide.
|
step guide.
|
||||||
|
|
||||||
* Contributing code
|
* Contributing code
|
||||||
Code contributions are welcome. Please read the following sections carefully. In
|
Code contributions are welcome. Please read the following sections carefully.
|
||||||
any case, feel free to join us on the [[https://gitter.im/syl20bnr/spacemacs][gitter chat]] to ask questions about
|
In any case, feel free to join us on the [[https://gitter.im/syl20bnr/spacemacs][gitter chat]] to ask questions about
|
||||||
contributing!
|
contributing!
|
||||||
|
|
||||||
** General contribution guidelines
|
** General contribution guidelines
|
||||||
|
@ -109,7 +110,8 @@ You may want to [[https://github.com/syl20bnr/spacemacs/wiki/Beginner%27s-Guide-
|
||||||
- One commit per PR
|
- One commit per PR
|
||||||
- If you have several commits on different topics, close the PR and
|
- If you have several commits on different topics, close the PR and
|
||||||
create one PR per topic
|
create one PR per topic
|
||||||
- If you still have several commits, squash them into only one commit ([[https://github.com/syl20bnr/spacemacs/pull/13381#pullrequestreview-380313280][here's a guide]])
|
- If you still have several commits, squash them into only one commit
|
||||||
|
([[https://github.com/syl20bnr/spacemacs/pull/13381#pullrequestreview-380313280][here's a guide]])
|
||||||
- Rebase your PR branch on top of upstream =develop= before submitting
|
- Rebase your PR branch on top of upstream =develop= before submitting
|
||||||
the PR
|
the PR
|
||||||
|
|
||||||
|
@ -204,12 +206,12 @@ The file header for =elisp= files should look like the following template:
|
||||||
#+END_EXAMPLE
|
#+END_EXAMPLE
|
||||||
|
|
||||||
You should replace =FILENAME= by the name of the file (e.g. =packages.el=), and
|
You should replace =FILENAME= by the name of the file (e.g. =packages.el=), and
|
||||||
and =NAME= by the name of the layer you are creating. =TYPE= should matchess the
|
=NAME= by the name of the layer you are creating. =TYPE= should match the
|
||||||
=FILENAME= (e.g. =funcs= for =funcs.el=). Don't forget to replace =YEAR=,
|
=FILENAME= (e.g. =funcs= for =funcs.el=). Don't forget to replace =YEAR=,
|
||||||
=YOUR_NAME=, and =YOUR_EMAIL= also. Some files already have a template inside
|
=YOUR_NAME=, and =YOUR_EMAIL= also. Some files already have a template inside
|
||||||
=core/templates/=, so look in there first.
|
=core/templates/=, so look in there first. Note that if you use
|
||||||
Note that if you use =configuration-layer/create-layer=, spacemacs will prepare
|
=configuration-layer/create-layer=, Spacemacs will prepare files and headers for
|
||||||
files and headers for you, and for free :smile: !
|
you, and for free :smile: !
|
||||||
|
|
||||||
*** Author of a new layer
|
*** Author of a new layer
|
||||||
In the files header, change the default author name (=Sylvain Benner=) to your
|
In the files header, change the default author name (=Sylvain Benner=) to your
|
||||||
|
@ -242,20 +244,21 @@ Tags are listed in [[https://github.com/syl20bnr/spacemacs/blob/develop/.ci/spac
|
||||||
|
|
||||||
Labels are used to name headlines in [[https://github.com/syl20bnr/spacemacs/blob/develop/layers/LAYERS.org][LAYERS.org]] file and
|
Labels are used to name headlines in [[https://github.com/syl20bnr/spacemacs/blob/develop/layers/LAYERS.org][LAYERS.org]] file and
|
||||||
[[https://github.com/syl20bnr/spacemacs/blob/develop/.ci/spacedoc-cfg.edn][:spacetools.spacedoc.config/layers-org-query]] defines structure of the file by
|
[[https://github.com/syl20bnr/spacemacs/blob/develop/.ci/spacedoc-cfg.edn][:spacetools.spacedoc.config/layers-org-query]] defines structure of the file by
|
||||||
chaining tags into a tree where every leaf turns into a list of
|
chaining tags into a tree where every leaf turns into a list of descriptions
|
||||||
descriptions pulled out of README.org files which tags match leaf's path in the tree.
|
pulled out of README.org files which tags match leaf's path in the tree. You can
|
||||||
You can see how the shape of [[https://github.com/syl20bnr/spacemacs/blob/develop/.ci/spacedoc-cfg.edn][<spacemacs_root>/.ci/spacedoc-cfg.edn]]
|
see how the shape of [[https://github.com/syl20bnr/spacemacs/blob/develop/.ci/spacedoc-cfg.edn][<spacemacs_root>/.ci/spacedoc-cfg.edn]] repeats in
|
||||||
repeats in [[https://github.com/syl20bnr/spacemacs/blob/develop/layers/LAYERS.org#table-of-contents][TOC of LAYERS.org]].
|
[[https://github.com/syl20bnr/spacemacs/blob/develop/layers/LAYERS.org#table-of-contents][TOC of LAYERS.org]].
|
||||||
|
|
||||||
Important details:
|
Important details:
|
||||||
- Every layer description will be displayed exacly one time.
|
- Every layer description will be displayed exactly one time.
|
||||||
- In the case when a README.org file of a layer doesn't have =#+TAGS:=
|
- When a README.org layer file doesn't have =#+TAGS:=, then the documentation
|
||||||
documentation formatting tool will inster dummy tags =layer|uncategorized=,
|
formatting tool will insert dummy tags =layer|uncategorized=, and such files
|
||||||
such files will be listed in [[https://github.com/syl20bnr/spacemacs/blob/develop/layers/LAYERS.org#readmeorg-files-that-need-proper-tags][LAYERS.org#readmeorg-files-that-need-proper-tags]].
|
will be listed in [[https://github.com/syl20bnr/spacemacs/blob/develop/layers/LAYERS.org#readmeorg-files-that-need-proper-tags][LAYERS.org#readmeorg-files-that-need-proper-tags]].
|
||||||
- Files which tag set has not being matched by [[https://github.com/syl20bnr/spacemacs/blob/develop/.ci/spacedoc-cfg.edn][:spacetools.spacedoc.config/layers-org-query]]
|
- Files with tags, that have not been matched by
|
||||||
will appire in [[https://github.com/syl20bnr/spacemacs/blob/develop/layers/LAYERS.org#skipped-layers][LAYERS.org#skipped-layers]]
|
[[https://github.com/syl20bnr/spacemacs/blob/develop/.ci/spacedoc-cfg.edn][:spacetools.spacedoc.config/layers-org-query]] will appear in
|
||||||
- If [[https://github.com/syl20bnr/spacemacs/blob/develop/layers/LAYERS.org][LAYERS.org]] file has =Skipped layers:= and/or
|
[[https://github.com/syl20bnr/spacemacs/blob/develop/layers/LAYERS.org#skipped-layers][LAYERS.org#skipped-layers]]
|
||||||
=README.org files that need proper tags= sections - someone is slacking :wink:
|
- If [[https://github.com/syl20bnr/spacemacs/blob/develop/layers/LAYERS.org][LAYERS.org]] has either or both of these sections: =Skipped layers:= and/or
|
||||||
|
=README.org files that need proper tags=, then someone is slacking :wink:
|
||||||
|
|
||||||
If you want to experiment with the tool locally:
|
If you want to experiment with the tool locally:
|
||||||
|
|
||||||
|
@ -271,21 +274,20 @@ If you are contributing to an already existing layer, you should not modify any
|
||||||
header file.
|
header file.
|
||||||
|
|
||||||
** Contributing a key binding
|
** Contributing a key binding
|
||||||
Key bindings are an important part of spacemacs.
|
Key bindings are an important part of Spacemacs.
|
||||||
|
|
||||||
First if you want to have some personal key bindings, you can freely bind them
|
First if you want to have some personal key bindings, you can freely bind them
|
||||||
inside the ~SPC o~ and ~SPC m o~ prefixes which are reserved for the user. This
|
inside the ~SPC o~ and ~SPC m o~ prefixes which are reserved for the user. This
|
||||||
can be done from the =dotspacemacs/user-config= function of your =.spacemacs=
|
can be done from the =dotspacemacs/user-config= function of your =.spacemacs=
|
||||||
file and don't require any contribution to Spacemacs.
|
file and don't require any contribution to Spacemacs.
|
||||||
|
|
||||||
If you think it worth contributing a new key bindings then be sure to read
|
If you think it worth contributing a new key bindings then be sure to read the
|
||||||
the [[https://github.com/syl20bnr/spacemacs/blob/develop/doc/CONVENTIONS.org][CONVENTIONS.org]] file to find the best key bindings, then create a
|
[[https://github.com/syl20bnr/spacemacs/blob/develop/doc/CONVENTIONS.org][CONVENTIONS.org]] file to find the best key bindings, then create a PR with your
|
||||||
PR with your changes.
|
changes.
|
||||||
|
|
||||||
*ALWAYS* document your new key bindings or key bindings changes inside the
|
*ALWAYS* document your new key bindings or key bindings changes inside the
|
||||||
relevant documentation file. It should be the layer's =README.org= file for
|
relevant documentation file. It should be the layer's =README.org= file for
|
||||||
layer's key bindings, or =DOCUMENTATION.org= for general Spacemacs key
|
layer's key bindings, or =DOCUMENTATION.org= for general Spacemacs key bindings.
|
||||||
bindings.
|
|
||||||
|
|
||||||
** Contributing a banner
|
** Contributing a banner
|
||||||
The startup banner is by default the Spacemacs logo but there are also ASCII
|
The startup banner is by default the Spacemacs logo but there are also ASCII
|
||||||
|
@ -309,7 +311,7 @@ tested by an independent reviewer. The steps:
|
||||||
the PR branch for hours or days to help stumble on unforeseen issues. Of
|
the PR branch for hours or days to help stumble on unforeseen issues. Of
|
||||||
course, common sense can be used and typo fixes do not need to be tested
|
course, common sense can be used and typo fixes do not need to be tested
|
||||||
against bugs, but be thorough in actual code changes. Testing with a fresh
|
against bugs, but be thorough in actual code changes. Testing with a fresh
|
||||||
spacemacs installation might be a good idea as well.
|
Spacemacs installation might be a good idea as well.
|
||||||
- Step back and think if the proposed changes could cause any other problems not
|
- Step back and think if the proposed changes could cause any other problems not
|
||||||
covered by your testing. You should also ask yourself whether or not you feel
|
covered by your testing. You should also ask yourself whether or not you feel
|
||||||
that your testing is adequate to confidently state that this PR introduces no
|
that your testing is adequate to confidently state that this PR introduces no
|
||||||
|
@ -340,7 +342,7 @@ token]] after which you can execute ~M-x forge-pull~. It will fetch all the PRs
|
||||||
which may take a few seconds as we have lot of PRs. Note also that all your
|
which may take a few seconds as we have lot of PRs. Note also that all your
|
||||||
Magit actions will get some additional delay due to the refresh of the PRs list.
|
Magit actions will get some additional delay due to the refresh of the PRs list.
|
||||||
|
|
||||||
Now, from the magit status buffer you can:
|
Now, from the Magit status buffer you can:
|
||||||
- checkout a PR with ~b y~ and searching it by name or ID
|
- checkout a PR with ~b y~ and searching it by name or ID
|
||||||
- donate all commits to develop by doing ~A d~ and selecting your current branch
|
- donate all commits to develop by doing ~A d~ and selecting your current branch
|
||||||
first and the develop branch second
|
first and the develop branch second
|
||||||
|
|
Loading…
Reference in New Issue