Skip to content

Commit 053836f

Browse files
uniqueguniqueg
authored
docs(contributors): restructure pages (#18)
1 parent 9aa657f commit 053836f

File tree

4 files changed

+374
-372
lines changed

4 files changed

+374
-372
lines changed

‎docs/guides/guide-contributor/general-guidelines.md

+264
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,264 @@
1+
# General guidelines
2+
3+
For your contributions, please follow the guidelines laid out below to the best
4+
of your ability.
5+
6+
??? note "Beginners"
7+
8+
If you don't have a lot of experience with this sort of workflow, the
9+
guidelines in this section may seem overwhelming. But please don't worry!
10+
We will guide you through the process and you will soon get the hang of it.
11+
And please don't worry about making mistakes either - everybody does them.
12+
Often! Our project layout makes it very very hard for anyone to cause
13+
irreversible harm, so relax, try things out, take your time and enjoy the
14+
work! :)
15+
16+
## Communication
17+
18+
Please use the comment functions available on GitHub to discuss issues and
19+
pull requests. For all other communications please refer to the communication
20+
channels listed in the [contact](../../about/contact.md) section. In
21+
particular, use the [chat][elixir-cloud-aai-slack] to discuss project ideas,
22+
get help on a problem, or any other informal discussion that does not need to
23+
be preserved as part of the repository you are working on.
24+
25+
## Submitting issues
26+
27+
Please use each project's GitHub issue tracker to:
28+
29+
- propose features
30+
- report bugs
31+
- find issues to work on
32+
- discuss existing issues
33+
34+
As an example, you can find this project's issue tracker
35+
[here][issue-tracker-example].
36+
37+
When submitting new issues to propose features or report bugs, please choose
38+
the most appropriate template, if available, then follow the instructions in
39+
the template.
40+
41+
You don't need to add labels or milestones for an issue, the project
42+
maintainers will do that for you. However, it is important that all issues are
43+
written concisely, yet with enough detail and relevant context (links,
44+
screenshots, etc.) to allow others to start working on them. For bug reports,
45+
it is essential that they include reproducible examples.
46+
47+
[Here][good-issues] and [here][good-bug-reports] are some resources to help you
48+
get started on writing good issues.
49+
50+
## Branching model
51+
52+
All of our projects are version-controlled via [Git][git] and codebases are
53+
hosted on [GitHub][github]. Please refer to appropriate documentation and
54+
tutorials if you are not familiar with them.
55+
56+
To keep track our project histories clean, we follow a slightly modified
57+
version of the [GitHub Flow][github-flow] Branching model. What this means is
58+
that code changes are always merged into protected branches via pull requests
59+
that will undergo one or more rounds of review and testing. The schema below
60+
visualizes this process.
61+
62+
[![GitHub Flow](../../images/github_flow.svg)][github-flow]
63+
64+
1. [Create a "feature branch"][git-branch] from the `dev` branch; use the
65+
`feature/my-feature` naming pattern to name your feature branch, e.g.,
66+
`feature/update-docs`; make sure the `dev` [branch
67+
is up to date][git-pull] before creating the feature branch!
68+
2. [Commit code changes][git-commit] to address the issue you are working on
69+
3. [Push the feature branch][git-push] to the remote and [create a pull
70+
request][github-pr] in GitHub
71+
4. Address any comments added during code review by pushing additional commits
72+
(there may be multiple rounds of reviews)
73+
5. Once all issues are resolved, code owners will merge the feature branch into
74+
the `dev` branch using the ["squash merging"][github-merge-squash] method
75+
76+
!!! note "Default branch"
77+
78+
`dev` is the default branch for all projects in pre-release state, i.e.,
79+
those with version numbers below `v1.0.0`. Upon release, `main` becomes
80+
the default branch, and [semantic versioning][sem-ver] is strictly adhered
81+
by.
82+
83+
??? note "Substantial changes"
84+
85+
If your proposed changes will be substantial, try to split up the work into
86+
multiple feature branches. This makes reviewing easier, helps to keep the
87+
project history clean and may better guard against code regression. A rule
88+
of thumb is that you should be able to adequately summarize your changes
89+
with 50 characters.
90+
91+
If your changes are becoming more substantial than you anticipated, you can
92+
request that the branch be ["rebase merged"][github-merge-rebase] instead
93+
of ["squash merged"][github-merge-squash]. However, we will only do so if
94+
you have exactly one clean commit for each semantic work package and each
95+
commit message follows the conventional commit specifications. You can use
96+
[`git rebase --interactive`][git-rebase] to clean up your feature branch.
97+
98+
??? warning "Feature branches unstable"
99+
100+
All feature branches are to be considered unstable, i.e., their history may
101+
change at any time, even after being pushed to the remote. Therefore, do
102+
**not** work on feature branches without clearly communicating with the
103+
people who have created them.
104+
105+
## Commit messages
106+
107+
Generally, no specific formatting of individual commit messages is required when
108+
working on _feature branches_. However, your **pull request titles MUST follow
109+
the [Conventional Commits specification][conv-commits]**. The same is true for
110+
individual commit messages if you are requesting that your feature branch be
111+
"rebase merged" (see info box "Substantial changes" above).
112+
113+
[Conventional Commits][conv-commits] help to increase consistency, facilitate
114+
maintenance and enable automated versioning and change log generation. Their
115+
general structure is as follows:
116+
117+
```console
118+
<type>(optional scope): <description>
119+
120+
[optional body]
121+
122+
[optional footer]
123+
```
124+
125+
Please follow these rules for your commit messages / PR titles:
126+
127+
- Keep your entire header/title line (including type and, if available, scope)
128+
at **50 characters or less**
129+
- Only use the types listed in the table below; choose the type according to the
130+
predominant reason for the change
131+
- Only use types `feat`, `fix`, `perf`, `refactor` and `style` for changes in
132+
package/production code; use the dedicated types for all build-, CI-,
133+
documentation- or test-related changes
134+
- Indicating a scope is optional; it is only necessary if scopes are generally
135+
used in the repository you are working on
136+
- Start the `<description>` with a verb in imperative form (e.g., `add`, `fix`)
137+
- If you include a body and/or footer, make sure it conforms to the
138+
Conventional Commits specification
139+
140+
Depending on the changes, we would kindly request you to use one of the
141+
following **type** prefixes:
142+
143+
| Type | Description |
144+
| --- | --- |
145+
| build | For changes related to the build system (e.g., scripts, configurations and tools) and package dependencies |
146+
| chore | For changes related to mundane repository maintenance tasks that are not covered by any of the other types (e.g., adding a `.gitignore file) |
147+
| ci | For changes related to the continuous integration and deployment system (e.g., workflows, scripts, configurations and tools) |
148+
| docs | For changes related to the project documentation, regardless of the audience (end users, developers) |
149+
| feat | For changes related to new abilities or functionality |
150+
| fix | For changes related to bug fixes |
151+
| perf | For changes related to performance improvements |
152+
| refactor | For changes related to modifying the codebase, which neither adds a feature nor fixes a bug (e.g., removing redundant code, simplifying code, renaming variables) |
153+
| revert | For changes that revert one or more previous commits |
154+
| style | For changes related to styling the codebase (e.g., indentation, parentheses/brackets, white space, trailing commas) |
155+
| test | For changes related to tests |
156+
157+
!!! info "Linting commit messages"
158+
159+
In order to ensure that the format of your commit messages adheres to the
160+
Conventional Commits specification and the defined type vocabulary, you can
161+
use a [dedicated linter][conv-commits-lint]. More information can also be
162+
found in this [blog post][conv-commits-blog].
163+
164+
## Filing pull requests
165+
166+
Open pull requests through the GitHub interface, VS Code or your favorite Git
167+
client. Make sure to follow the branching model. Most importantly:
168+
169+
??? warning "Use Conventional Commit messages for your PR titles!"
170+
171+
See details in the [commit message](#commit-messages) section.
172+
173+
### Code reviews
174+
175+
All code changes are reviewed by at least one other person. This is to ensure
176+
that the code is of high quality, that it is well-documented and that it adheres
177+
to the project's coding standards. The reviewer will check that the code is
178+
correct, that it is efficient and that it is maintainable. They will also check
179+
that the code is well-documented and that it is tested.
180+
181+
Please make sure to actively request reviews for your pull requests to avoid
182+
delays in the review and merging process. Please use the GitHub functionality
183+
for that (upper right hand corner of pull request view). If you are unsure who
184+
to ask for a review, please reach out to the project leads.
185+
186+
### Pull request template
187+
188+
The following pull request template will be successively added to all
189+
repositories. Until that is the case, you can already make use of it by
190+
self-reviewing your pull requests according to the checklist and descriptions.
191+
192+
#### Description
193+
194+
> Please include a summary of the change and the relevant issue(s) it resolves,
195+
> if any (otherwise delete that line), e.g., `Fixes #123`. If the PR addresses
196+
> more than one issue, please add multiple lines, each starting with 'Fixes #'.
197+
> Please stick to that syntax precisely, including whitespaces, otherwise the
198+
> issue(s) may not be linked to the PR.
199+
>
200+
> In the summary, list any dependencies that are required for this change.
201+
> Please use bullet points for the description. Please also briefly describe
202+
> the relevant motivation and context briefly. For very trivial changes that are
203+
> duly explained by the PR title, a description can be omitted.
204+
205+
-
206+
207+
Fixes #(issue number)
208+
209+
#### Checklist
210+
211+
> Please go through the following checklist to ensure that your change is ready
212+
> for review. Please do not forget to double check the list after you have
213+
> modified your PR, e.g., if you have added commits to address reviewer
214+
> comments or to fix failing automated checks. **Please check items also if they
215+
> do not apply to your change**, e.g., if your change does not require an update
216+
> of the user-facing documentation, still check the box.
217+
>
218+
> Generally, **PRs are only reviewed when all boxes are ticked off and all
219+
> automated checks pass** (use the comment section below if you believe that
220+
> your PR is ready to be merged even though not all boxes were ticked off).
221+
222+
- [ ] My code follows the [contributing guidelines](workflow.md) of this
223+
project, including, in particular, with regard to any style guidelines
224+
- [ ] The title of my PR complies with the [Conventional Commits
225+
specification][conv-commits]; in particular, it clearly indicates
226+
that a change is a breaking change
227+
- [ ] I acknowledge that all my commits will be squashed into a single commit,
228+
using the PR title as the commit message
229+
- [ ] I have performed a self-review of my own code
230+
- [ ] I have commented my code in hard-to-understand areas
231+
- [ ] I have updated the user-facing documentation to describe any new or
232+
changed behavior
233+
- [ ] I have added type annotations for all function/class/method interfaces
234+
or updated existing ones (only for Python, TypeScript, etc.)
235+
- [ ] I have provided appropriate documentation (e.g., [Google-style
236+
Python docstrings][py-doc-google] or [JSDoc block tags][jsdoc]) for all
237+
packages/modules/functions/classes/methods or updated existing ones
238+
- [ ] My changes generate no new warnings
239+
- [ ] I have added tests that prove my fix is effective or that my feature
240+
works
241+
- [ ] New and existing unit tests pass locally with my changes
242+
- [ ] I have not reduced the existing code coverage
243+
- [ ] I have asked the [@all-contributors bot][all-contributors-bot] to
244+
acknowledge my contributions by commenting on this PR with a request of
245+
the form `@all-contributors please add @YOUR_GH_HANDLE for TYPE_1,
246+
TYPE_2, ...`, where `TYPE_1` etc. refer to [contribution types supported
247+
by the All Contributors Specification][all-contributors-types] OR I do
248+
not want my contributions to be acknowledged by [All
249+
Contributors][all-contributors]
250+
251+
!!! note "All Contributors"
252+
253+
The [All Contributors][all-contributors] bot may not be available in all
254+
repositories yet. In that case, please ignore the last bullet point.
255+
256+
#### Comments
257+
258+
> If there are unchecked boxes in the list above, but you would still like your
259+
> PR to be reviewed or considered for merging, please describe here why boxes
260+
> were not checked. For example, if you are positive that your commits should
261+
> _not_ be squased when merging, please explain why you think the PR warrants
262+
> or requires multiple commits to be added to the history (but note that in
263+
> that case, it is a prerequisite that all commits follow the Conventional
264+
> Commits specification).

‎docs/guides/guide-contributor/managing-projects.md

+104
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Managing your own project
2+
3+
If you are managing a project by yourself or with others, please follow these
4+
additional guidelines below.
5+
6+
## Community standards
7+
8+
Please try to adhere to best community standards. To help with that, visit
9+
GitHub's "Community Standards" section (accessible in each repository via the
10+
"Insights" tab) and confirm that the following are available in the repository
11+
root directory:
12+
13+
- **README** in file `README.md`
14+
- **Code of Conduct** in file `CODE_OF_CONDUCT.md` (can link to the [Code of
15+
Conduct](../../about/code-of-conduct.md) on this page)
16+
- **Contributing guidelines** in file `CONTRIBUTING.md` (can link to the
17+
[contributor guide](index.md) on this page)
18+
- **License** in file `LICENSE`
19+
- **Pull request template** in file `PULL_REQUEST_TEMPLATE.md`
20+
21+
Also make sure that a project **description** (right hand panel on the
22+
repository's main page) and one or more **issue templates** (in
23+
`.github/ISSUE_TEMPLATE`) are available.
24+
25+
## Licensing
26+
27+
All projects must be licensed under an [Open Source Initiative
28+
(OSI)][osi]-approved license. The license must be included in the repository
29+
root directory in a file named `LICENSE`. Unless otherwise discussed, please
30+
use the [Apache License 2.0][license-apache].
31+
32+
## Versioning
33+
34+
All our projects are versioned according to the [Semantic Versioning][sem-ver]
35+
specification. This means that each version number consists of three parts:
36+
`MAJOR.MINOR.PATCH`. The version number is increased as follows:
37+
38+
- `MAJOR` version is increased when you make incompatible/breaking API changes
39+
- `MINOR` version is increased when you add functionality in a backwards
40+
compatible manner
41+
- `PATCH` version is increased when you make backwards compatible bug fixes
42+
43+
Note that projects in pre-release state, i.e., should be assigned a version
44+
number below `1.0.0` (start with `0.1.0`). In Semantic Versioning, this means
45+
that API changes can occur at any moment, which is suitable for a project that
46+
has not reached sufficient maturity and API stability yet.
47+
48+
## Continuous Integration
49+
50+
We are fully embracing the concept of continuous integration (CI) and related
51+
practices. This means that all code changes are automatically tested and
52+
validated before they are merged into the main codebase. This is to ensure that
53+
the codebase remains stable and that new features and bug fixes do not break
54+
existing functionality.
55+
56+
Therefore, when starting a new project, as soon as possible, please add one or
57+
more GitHub Actions workflows to your project that do the following for pushes
58+
to and pull requests against the repository's default branch (see existing
59+
projects for examples):
60+
61+
- Run linting and formatting checks
62+
- Run type checks (if applicable)
63+
- Run unit and integration tests
64+
- Check test coverage and upload results to [Codecov][codecov]
65+
- Build and publish documentation (if not set up to be triggered automatically
66+
by the publishing system, e.g., Read the Docs)
67+
68+
!!! note "Continuous Delivery/Deployment"
69+
70+
If the project you are working on is reasonably mature, also consider
71+
setting up one or more continuous delivery/deployment workflows.
72+
73+
## Documentation
74+
75+
Related to continuous integration, we also value continuous documentation. This
76+
means that documentation is updated and improved as the codebase evolves. This
77+
is to ensure that the documentation remains accurate and up-to-date and that it
78+
reflects the current state of the codebase. It also means that we want to start
79+
writing documentation as early as possible.
80+
81+
Currently, we are using Markdown to write documentation. For new projects, we
82+
expect that each project has a `README.md` file that covers the following
83+
sections (fill in with "Coming soon" if not yet available):
84+
85+
- **Synopsis**: A brief description of the project
86+
- **Basic usage**: A brief overview of how to use the project
87+
- **Installation**: Instructions on how to install/deploy the project
88+
- **Versioning**: Information on how the project is versioned
89+
- **Contributing**: Guidelines on how to contribute to the project, with links
90+
to the [contributing guidelines](index.md) and our
91+
[code of conduct](../../about/code-of-conduct.md)
92+
- **Contact**: Information on how to contact the project leads
93+
94+
### Hosted documentation
95+
96+
As projects grow, a simple `README.md` will not be sufficient anymore.
97+
98+
We therefore kindly ask you to prepare a dedicated, hosted documentation page
99+
early on. This can be done using services like [Read the Docs][read-the-docs] or
100+
GitHub Pages with MKDocs (like this page).
101+
102+
Carefully consider the audiences for your project and tailor the documentation
103+
accordingly. In all cases, we expect that API documentation is made available
104+
(can be auto-generated from code, e.g., via [Sphinx][sphinx]).

0 commit comments

Comments
 (0)