Skip to content

Commit 6e3040b

Browse files
loucasalCopilotkeunes
authored
Import contributor documentation from GitHub wiki (#398)
* import and update wiki content * Tweak image and table styling --------- Co-authored-by: Copilot <[email protected]> Co-authored-by: Keunes <[email protected]>
1 parent d0754cb commit 6e3040b

File tree

12 files changed

+106
-9
lines changed

12 files changed

+106
-9
lines changed

‎_contribute/develop/app/code-style.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
layout: doc
3+
texts: contribute.develop.categories.app.code-style
4+
icon: "fa-solid fa-code"
5+
order: 10
6+
parent: app
7+
---
8+
9+
# {% t {{ page.texts }}.title %}
10+
11+
{% tf {{ page.url | remove_first: "/" }}.md %}

‎_contribute/develop/app/getting-credited.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
layout: doc
3+
texts: contribute.develop.categories.app.getting-credited
4+
icon: "fa-solid fa-award"
5+
order: 30
6+
parent: app
7+
---
8+
9+
# {% t {{ page.texts }}.title %}
10+
11+
{% tf {{ page.url | remove_first: "/" }}.md %}

‎_contribute/develop/app/test-builds.md

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
---
2+
layout: doc
3+
texts: contribute.develop.categories.app.test-builds
4+
icon: "fa-solid fa-vial-circle-check"
5+
order: 20
6+
parent: app
7+
---
8+
9+
# {% t {{ page.texts }}.title %}
10+
11+
{% tf {{ page.url | remove_first: "/" }}.md %}

‎_i18n/en.yml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -119,6 +119,12 @@ contribute:
119119
app:
120120
title: "App"
121121
card-text: "You speak Java? Find out how to contribute to the AntennaPod app."
122+
code-style:
123+
title: "Code structure & code style"
124+
test-builds:
125+
title: "Getting test builds"
126+
getting-credited:
127+
title: "Getting credited for your contribution"
122128
website:
123129
title: "Website"
124130
card-text: "Familiar with SCSS and HTML? Help us out with our website."

‎_i18n/en/contribute/develop/app.md

Lines changed: 6 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,14 @@
11
You're right at it: the core of the project! Used by thousands of people across the world, your contributions are an important contribution to an open podcasting ecosystem. So, are you experienced with Java, or just getting started? We welcome your contributions in our [GitHub repository](https://github.com/AntennaPod/AntennaPod).
22

33
## Where we need help
4-
There's a few areas where we could well use your support. When first getting started to AntennaPod development, we recommend to pick an issue with the ['Good first issue' label](https://github.com/AntennaPod/AntennaPod/labels/Good%20first%20issue) on GitHub. Before you start working on an issue, make sure that it does not have the 'Needs: Triage' or 'Needs: Decision' label. Those labels mean that the feature was not reviewed by the core AntennaPod team yet.
4+
There are a few areas where we could well use your support. When first getting started to AntennaPod development, we recommend to pick an issue with the ['Good first issue' label](https://github.com/AntennaPod/AntennaPod/labels/Good%20first%20issue) on GitHub. Before you start working on an issue, make sure that it does not have the 'Needs: Triage' or 'Needs: Decision' label. Those labels mean that the feature was not reviewed by the core AntennaPod team yet.
55

6-
If you prefer bug-hunting, your go-to list for a weekend bug-hunt is the ['confirmed bugs' issue label](https://github.com/AntennaPod/AntennaPod/labels/Type%3A%20Confirmed%20bug) on GitHub.
6+
If you prefer hunting bugs, your go-to list for a weekend bug-hunt is the ['confirmed bugs' issue label](https://github.com/AntennaPod/AntennaPod/labels/Type%3A%20Confirmed%20bug) on GitHub.
77

88
## Getting started
9-
**Before** Please don't just submit a PR, but always *announce your interest first*. Sometimes we didn't yet reach an agreement on a user experience and interface. It can happen that someone agreed to start working on something, but we forgot to 'assign' the GitHub issue. Chipping in on our forum is the best way to avoid lost hours on code that won't be accepted.
9+
Before submitting a pull request, always *announce your interest first*. Sometimes we haven't reached an agreement on a user experience and interface yet. Or it can happen that someone volunteered to start working on something, but we forgot to 'assign' the GitHub issue. Chipping in on our [forum](https://forum.antennapod.org) is the best way to avoid losing hours on code that won't be accepted.
1010

11-
**During** Have a look at our wiki; it contains [handy info for contributors](https://github.com/AntennaPod/AntennaPod/wiki). You'll find there, for example, information about the project's [code style](https://github.com/AntennaPod/AntennaPod/wiki/Code-style) and can learn [how to make sure you get accredited](https://github.com/AntennaPod/AntennaPod/wiki/Getting-accredited-on-the-Contributors-page) for your work in the app. Last but not least: build instructions and info about debug logs.
11+
To keep things tidy, we prefer to have broader discussions on features on our forum. Once a decision has been reached, a concrete and boiled down description of the desired solution will be added to the relevant issue. More technical discussions on how to implement that can then take place in pull requests.
1212

13-
**After** Talk about your work, and claim that fame! It might inspire other potential contributors, and helps promote the app generally. We're happy to retweet your tweets!
14-
15-
# Get in touch!
16-
Vaguely interested but not sure yet? Ready to get started? Get in touch with @Keunes or @ByteHamster on [our forum](https://forum.antennapod.org)!
13+
## Get in touch!
14+
Vaguely interested but not sure yet? Ready to get started? Get in touch with @Keunes or @ByteHamster on [our forum](https://forum.antennapod.org) or join the next [community meeting](https://antennapod.org/events/community-meeting)!

‎_i18n/en/contribute/develop/app/code-style.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
AntennaPod is structured in several modules to ensure that similar code is close together and to avoid cyclic dependencies, which makes sure that the code can easily be tested. As an initial overview, the figure below gives the structure of all AntennaPod modules.
2+
3+
{% include image.html
4+
alt="A graph with 31 ovals and a recognizable set of arrows between them."
5+
loc="/assets/images/blog/2024"
6+
file="codeStructureAfter.png"
7+
%}
8+
9+
For the Java code, AntennaPod uses a style similar to [Google's Java style](https://google.github.io/styleguide/javaguide.html). Checkstyle is run automatically when creating a pull request.
10+
11+
For Android layout XML files, we use indentation with 4 spaces. The `id`, `layout_width` and `layout_height` attributes come first. To easily format the files, you can use the same [tool](https://github.com/ByteHamster/android-xml-formatter) as our CI server.
12+
13+
### Resource ID naming
14+
Please use lowerCamelCase for naming `@+id` resources. For some types listed in the table below, please add a suffix noting the type.
15+
16+
| View type | Examples | Naming |
17+
| --- | --- | --- |
18+
| Clickable items where only the action is important | `Button` that opens Settings, `ImageView` that triggers play/pause | Add suffix `Button`, even if it is not a Button view. Here, the action is more important than the view type. |
19+
| `ViewGroup` like `LinearLayout`, `FrameLayout` | `LinearLayout` that shows player controls, `FrameLayout` that allows to hide the whole screen content while loading | Add suffix `Container`. In most cases, the Java code does not care what specific `ViewGroup` is used. It just cares that it can hide a group of other items. Cases where the actual type is especially important, such as `suggestionsGrid`, can be named differently. |
20+
| Images whose main purpose is to show an image (as opposed to mainly being a button) | `ImageView` that serves as a background, `SquareImageView` that shows the cover | Add suffix `Image` |
21+
| Text content | `TextView` that shows the position | Add suffix `Label` |
22+
| Everything else | `Spinner` that allows to select options, `ProgressBar` that shows the position | Suffix with shortened view type. This ensures that a reader of the code knows what a view can be used for without looking at the layout files |
23+
24+
In cases where adding a name would be redundant, it may also be named only after the type of the element (for example `recyclerView`, `progressBar`).

‎_i18n/en/contribute/develop/app/getting-credited.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
To be credited on the Contributors page on GitHub and in the app, your commits must be linked to your GitHub account. Simply create the commits with an email address that is linked to your GitHub account (or add that email address to GitHub). You can verify if it worked by checking whether the icon below the commit shows your profile picture.
2+
3+
To change the author of the most recent commit, you can run a command such as `git commit --amend --author="John Doe <[email protected]>"`. Changing something that way requires to force-push the changes (`git push --force`). To change multiple commits, have a look at [interactive rebase](https://thoughtbot.com/blog/git-interactive-rebase-squash-amend-rewriting-history).
4+
5+
If you don't care about appearing on the Contributors page, please indicate this in your pull request.
6+
7+
After your work is merged, we also encourage you to talk about it and claim that fame! It might inspire other potential contributors, and helps promote the app generally. We're happy to retweet your tweets!

‎_i18n/en/contribute/develop/app/test-builds.md

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
You can obtain development builds directly from GitHub. Every time the CI server performs automated tests on the code, it also creates an apk file that you can try. **These builds are not meant for daily use.** As they are debug builds, they are significantly slower/laggier and they may crash when detecting some (usually unproblematic) programming errors, instead of ignoring them like release builds. Use them for testing only.
2+
3+
- Open a branch to view the commits, click the checkmark (or cross) icon and select any of the tests:
4+
{% include image.html
5+
width="250"
6+
alt="An image showing completed checks on a branch, with an arrow pointing to the Details link."
7+
loc="/assets/images/contribute"
8+
file="testbuild1.png"
9+
%}
10+
- Choose `Summary`:
11+
{% include image.html
12+
width="250"
13+
alt="An image with an arrow pointing to the Summary link for checks on a branch."
14+
loc="/assets/images/contribute"
15+
file="testbuild2.png"
16+
%}
17+
- Scroll down and download the artifact:
18+
{% include image.html
19+
width="250"
20+
alt="An image with an arrow pointing to a test build generated by the CI server."
21+
loc="/assets/images/contribute"
22+
file="testbuild3.png"
23+
%}

‎_sass/_custom.scss

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -563,7 +563,7 @@ blockquote {
563563
line-height: 1.5rem;
564564
}
565565

566-
& p + p, div.modal + p {
566+
& p + p, div.modal + p, p + table, table + p {
567567
margin-top: 20px;
568568
}
569569

@@ -657,6 +657,12 @@ blockquote {
657657
color: $gray-800;
658658
}
659659

660+
& td, th {
661+
border-color: var(--secondary);
662+
border-width: 1px;
663+
border-style: solid;
664+
padding: 3px 6px;
665+
}
660666
}
661667

662668
.post-content + .row, p + .row {

‎assets/images/contribute/testbuild1.png

41.4 KB
Loading

0 commit comments

Comments
 (0)