Skip to content

Commit 6a1d07b

Browse files
fredbifredbi
committed
doc: announced new discord channel
Signed-off-by: Frederic BIDON <[email protected]>
1 parent 5f3094b commit 6a1d07b

File tree

7 files changed

+578
-91
lines changed

7 files changed

+578
-91
lines changed

‎.github/CONTRIBUTING.md‎

Lines changed: 172 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -1,114 +1,211 @@
11
## Contribution Guidelines
22

3+
You'll find below general guidelines, which mostly correspond to standard practices for open sourced repositories.
4+
5+
>**TL;DR**
6+
>
7+
> If you're already an experienced go developer on github, then you should just feel at home with us
8+
> and you may well skip the rest of this document.
9+
>
10+
> You'll essentially find the usual guideline for a go library project on github.
11+
12+
These guidelines are general to all libraries published on github by the `go-openapi` organization.
13+
14+
You'll find more detailed (or repo-specific) instructions in the [maintainer's docs](../docs).
15+
16+
## How can I contribute?
17+
18+
There are many ways in which you can contribute. Here are a few ideas:
19+
20+
* Reporting Issues / Bugs
21+
* Suggesting Improvements
22+
* Code
23+
* bug fixes and new features that are within the main project scope
24+
* improving test coverage
25+
* addressing code quality issues
26+
* Documentation
27+
* Art work that makes the project look great
28+
29+
## Questions & issues
30+
31+
### Asking questions
32+
33+
You may inquire about anything about this library by reporting a "Question" issue on github.
34+
35+
### Reporting issues
36+
37+
Reporting a problem with our libraries _is_ a valuable contribution.
38+
39+
You can do this on the github issues page of this repository.
40+
41+
Please be as specific as possible when describing your issue.
42+
43+
Whenever relevant, please provide information about your environment (go version, OS).
44+
45+
Adding a code snippet to reproduce the issue is great, and as a big time saver for maintainers.
46+
47+
### Triaging issues
48+
49+
You can help triage issues which may include:
50+
51+
* reproducing bug reports
52+
* asking for important information, such as version numbers or reproduction instructions
53+
* answering questions and sharing your insight in issue comments
54+
55+
## Code contributions
56+
357
### Pull requests are always welcome
458

5-
We are always thrilled to receive pull requests, and do our best to
6-
process them as fast as possible. Not sure if that typo is worth a pull
7-
request? Do it! We will appreciate it.
59+
We are always thrilled to receive pull requests, and we do our best to
60+
process them as fast as possible.
61+
62+
Not sure if that typo is worth a pull request? Do it! We will appreciate it.
63+
64+
If your pull request is not accepted on the first try, don't be discouraged!
65+
If there's a problem with the implementation, hopefully you received feedback on what to improve.
66+
67+
If you have a lot of ideas or a lot of issues to solve, try to refrain a bit and post focused
68+
pull requests.
69+
Think that they must be reviewed by a maintainer and it is easy to lost track of things on big PRs.
70+
71+
We're trying very hard to keep the go-openapi packages lean and focused.
72+
These packages constitute a toolkit: it won't do everything for everybody out of the box,
73+
but everybody can use it to do just about everything related to OpenAPI.
74+
75+
This means that we might decide against incorporating a new feature.
76+
77+
However, there might be a way to implement that feature *on top of* our libraries.
78+
79+
### Environment
80+
81+
You just need a `go` compiler to be installed. No special tools are needed to work with our libraries.
82+
83+
The go compiler version required is always the old stable (latest minor go version - 1).
884

9-
If your pull request is not accepted on the first try, don't be
10-
discouraged! If there's a problem with the implementation, hopefully you
11-
received feedback on what to improve.
85+
If you're already used to work with `go` you should already have everything in place.
1286

13-
We're trying very hard to keep go-swagger lean and focused. We don't want it
14-
to do everything for everybody. This means that we might decide against
15-
incorporating a new feature. However, there might be a way to implement
16-
that feature *on top of* go-swagger.
87+
Although not required, you'll be certainly more productive with a local installation of `golangci-lint`,
88+
the meta-linter our CI uses.
1789

90+
If you don't have it, you may install it like so:
91+
92+
```sh
93+
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@latest
94+
```
1895

1996
### Conventions
2097

21-
Fork the repo and make changes on your fork in a feature branch:
98+
#### Git flow
99+
100+
Fork the repo and make changes to your fork in a feature branch.
101+
102+
To submit a pull request, push your branch to your fork (e.g. `upstream` remote):
103+
github will propose to open a pull request on the original repository.
104+
105+
Typically you'd follow some common naming conventions:
106+
107+
- if it's a bugfix branch, name it `fix/XXX-something`where XXX is the number of the
108+
issue on github
109+
- if it's a feature branch, create an enhancement issue to announce your
110+
intentions, and name it `feature/XXX-something` where XXX is the number of the issue.
111+
112+
> NOTE: we don't enforce naming conventions on branches: it's your fork after all.
113+
114+
#### Tests
115+
116+
Submit unit tests for your changes.
117+
118+
Go has a great built-in test framework ; use it!
119+
120+
Take a look at existing tests for inspiration, and run the full test suite on your branch
121+
before submitting a pull request.
122+
123+
Our CI measures test coverage and the test coverage of every patch.
124+
Although not a blocking step - because there are so many special cases -
125+
this is an indicator that maintainers consider when approving a PR.
126+
127+
Please try your best to cover about 80% of your patch.
128+
129+
#### Code style
22130

23-
- If it's a bugfix branch, name it XXX-something where XXX is the number of the
24-
issue
25-
- If it's a feature branch, create an enhancement issue to announce your
26-
intentions, and name it XXX-something where XXX is the number of the issue.
131+
You may read our stance on code style [there](../docs/STYLE.md).
27132

28-
Submit unit tests for your changes. Go has a great test framework built in; use
29-
it! Take a look at existing tests for inspiration. Run the full test suite on
30-
your branch before submitting a pull request.
133+
#### Documentation
31134

32-
Update the documentation when creating or modifying features. Test
33-
your documentation changes for clarity, concision, and correctness, as
34-
well as a clean documentation build. See ``docs/README.md`` for more
35-
information on building the docs and how docs get released.
135+
Don't forget to update the documentation when creating or modifying features.
36136

37-
Write clean code. Universally formatted code promotes ease of writing, reading,
38-
and maintenance. Always run `gofmt -s -w file.go` on each changed file before
39-
committing your changes. Most editors have plugins that do this automatically.
137+
Most documentation for this library is directly found in code as comments for godoc.
138+
139+
The documentation for the go-openapi packages is published on the public go docs site:
140+
141+
<https://pkg.go.dev/github.com/go-openapi/jsonpointer>
142+
143+
Check your documentation changes for clarity, concision, and correctness.
144+
145+
If you want to assess the rendering of your changes when published to `pkg.go.dev`, you may
146+
want to install the `pkgsite` tool proposed by `golang.org`.
147+
148+
```sh
149+
go install golang.org/x/pkgsite/cmd/pkgsite@latest
150+
```
151+
152+
Then run on the repository folder:
153+
```sh
154+
pkgsite .
155+
```
156+
157+
This wil run a godoc server locally where you may see the documentation generated from your local repository.
158+
159+
#### Commit messages
40160

41161
Pull requests descriptions should be as clear as possible and include a
42162
reference to all the issues that they address.
43163

44164
Pull requests must not contain commits from other users or branches.
45165

46-
Commit messages must start with a capitalized and short summary (max. 50
47-
chars) written in the imperative, followed by an optional, more detailed
48-
explanatory text which is separated from the summary by an empty line.
166+
Commit messages are not required to follow the "conventional commit" rule, but it's certainly a good
167+
thing to follow this guidelinea (e.g. "fix: blah blah", "ci: did this", "feat: did that" ...).
49168

50-
Code review comments may be added to your pull request. Discuss, then make the
51-
suggested modifications and push additional commits to your feature branch. Be
52-
sure to post a comment after pushing. The new commits will show up in the pull
53-
request automatically, but the reviewers will not be notified unless you
54-
comment.
169+
The title in your commit message is used directly to produce our release notes: try to keep them neat.
55170

56-
Before the pull request is merged, make sure that you squash your commits into
57-
logical units of work using `git rebase -i` and `git push -f`. After every
58-
commit the test suite should be passing. Include documentation changes in the
59-
same commit so that a revert would remove all traces of the feature or fix.
171+
The commit message body should detail your changes.
60172

61-
Commits that fix or close an issue should include a reference like `Closes #XXX`
62-
or `Fixes #XXX`, which will automatically close the issue when merged.
173+
If an issue should be closed by a commit, please add this reference in the commit body:
63174

64-
### Sign your work
175+
```
176+
* fixes #{issue number}
177+
```
65178

66-
The sign-off is a simple line at the end of the explanation for the
67-
patch, which certifies that you wrote it or otherwise have the right to
68-
pass it on as an open-source patch. The rules are pretty simple: if you
69-
can certify the below (from
70-
[developercertificate.org](http://developercertificate.org/)):
179+
#### Code review
71180

72-
```
73-
Developer Certificate of Origin
74-
Version 1.1
181+
Code review comments may be added to your pull request.
75182

76-
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
77-
660 York Street, Suite 102,
78-
San Francisco, CA 94110 USA
183+
Discuss, then make the suggested modifications and push additional commits to your feature branch.
79184

80-
Everyone is permitted to copy and distribute verbatim copies of this
81-
license document, but changing it is not allowed.
185+
Be sure to post a comment after pushing. The new commits will show up in the pull
186+
request automatically, but the reviewers will not be notified unless you comment.
82187

188+
Before the pull request is merged,
189+
**make sure that you squash your commits into logical units of work**
190+
using `git rebase -i` and `git push -f`.
83191

84-
Developer's Certificate of Origin 1.1
192+
After every commit the test suite should be passing.
85193

86-
By making a contribution to this project, I certify that:
194+
Include documentation changes in the same commit so that a revert would remove all traces of the feature or fix.
87195

88-
(a) The contribution was created in whole or in part by me and I
89-
have the right to submit it under the open source license
90-
indicated in the file; or
196+
#### Sign your work
91197

92-
(b) The contribution is based upon previous work that, to the best
93-
of my knowledge, is covered under an appropriate open source
94-
license and I have the right under that license to submit that
95-
work with modifications, whether created in whole or in part
96-
by me, under the same open source license (unless I am
97-
permitted to submit under a different license), as indicated
98-
in the file; or
198+
The sign-off is a simple line at the end of your commit message,
199+
which certifies that you wrote it or otherwise have the right to
200+
pass it on as an open-source patch.
99201

100-
(c) The contribution was provided directly to me by some other
101-
person who certified (a), (b) or (c) and I have not modified
102-
it.
202+
We require the simple DCO below with an email signing your commit.
203+
PGP-signed commit are greatly appreciated but not required.
103204

104-
(d) I understand and agree that this project and the contribution
105-
are public and that a record of the contribution (including all
106-
personal information I submit with it, including my sign-off) is
107-
maintained indefinitely and may be redistributed consistent with
108-
this project or the open source license(s) involved.
109-
```
205+
The rules are pretty simple:
110206

111-
then you just add a line to every git commit message:
207+
* read our [DCO](./DCO.md) (from [developercertificate.org](http://developercertificate.org/))
208+
* if you agree with these terms, then you just add a line to every git commit message
112209

113210
Signed-off-by: Joe Smith <[email protected]>
114211

‎.github/DCO.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# Developer's Certificate of Origin
2+
3+
```
4+
Developer Certificate of Origin
5+
Version 1.1
6+
7+
Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
8+
660 York Street, Suite 102,
9+
San Francisco, CA 94110 USA
10+
11+
Everyone is permitted to copy and distribute verbatim copies of this
12+
license document, but changing it is not allowed.
13+
14+
15+
Developer's Certificate of Origin 1.1
16+
17+
By making a contribution to this project, I certify that:
18+
19+
(a) The contribution was created in whole or in part by me and I
20+
have the right to submit it under the open source license
21+
indicated in the file; or
22+
23+
(b) The contribution is based upon previous work that, to the best
24+
of my knowledge, is covered under an appropriate open source
25+
license and I have the right under that license to submit that
26+
work with modifications, whether created in whole or in part
27+
by me, under the same open source license (unless I am
28+
permitted to submit under a different license), as indicated
29+
in the file; or
30+
31+
(c) The contribution was provided directly to me by some other
32+
person who certified (a), (b) or (c) and I have not modified
33+
it.
34+
35+
(d) I understand and agree that this project and the contribution
36+
are public and that a record of the contribution (including all
37+
personal information I submit with it, including my sign-off) is
38+
maintained indefinitely and may be redistributed consistent with
39+
this project or the open source license(s) involved.
40+
```

0 commit comments

Comments
 (0)